@wzfukui/ani 2026.3.28

package/README.md

@@ -0,0 +1,154 @@
+# @wzfukui/ani
+
+OpenClaw channel plugin for [Agent-Native IM (ANI)](https://github.com/wzfukui/agent-native-im), a messaging platform built for human and AI bot collaboration. Version **2026.3.28**.
+
+## Features
+
+- **Bidirectional messaging** -- receive messages via WebSocket, send replies immediately via REST API (not buffered)
+- **Tools**: `ani_send_file`, `ani_fetch_chat_history_messages`, `ani_list_conversation_tasks`, `ani_get_task`, `ani_create_task`, `ani_update_task`, `ani_delete_task`
+- **Streaming progress** -- long-running tasks show real-time status in chat via status layers with typing indicators
+- **Artifact rendering** -- `<artifact>` tags in model output sent as structured content (HTML, code, mermaid)
+- **File handling** -- send/receive images, documents, audio, video, archives (up to 32 MB); small text files inlined for AI, protected binary files downloaded with ANI auth and saved to local media paths
+- **Multi-bot collaboration** -- group conversations with multiple bots, @mention routing, conversation context injection
+- **Message revoke listener** -- detects `message.revoked` events and aborts in-flight delivery for that message
+- **Stream cancel abort** -- `stream.cancel` / `task.cancel` events abort the active agent dispatch via AbortController
+- **Reactions** -- ack-reaction on message receipt (configurable via `messages.ackReaction`)
+- **Interactive cards** -- approval/selection UI via ANI's interaction layer
+- **Message chunking** -- long replies split at markdown boundaries (configurable limit)
+- **Auto-reconnecting WebSocket** -- ping/pong keepalive with exponential backoff
+- **Retry with exponential backoff** -- REST calls retry on transient failures (502/503/504) with jitter
+- **Config hot reload** -- changes under `channels.ani` auto-detected; most take effect without restart
+- **Multi-agent routing** -- route specific conversations to dedicated OpenClaw agents with separate workspaces
+
+## Quick Start
+
+### Option A: Install from npm
+
+```bash
+openclaw plugins install @wzfukui/ani
+```
+
+### Option B: Install from local extension
+
+```bash
+# From the OpenClaw repo with extensions/ani/ present
+openclaw plugins install ./extensions/ani
+```
+
+### Configure
+
+```bash
+# 1. Set ANI server and API key (create a Bot in ANI Web to get the key)
+openclaw config set channels.ani.serverUrl "https://your-ani-server.example.com"
+openclaw config set channels.ani.apiKey "aim_your_api_key"
+
+# 2. Enable the tools
+openclaw config set tools.alsoAllow '["ani_send_file","ani_fetch_chat_history_messages","ani_list_conversation_tasks","ani_get_task","ani_create_task","ani_update_task","ani_delete_task"]' --strict-json
+
+# 3. Check the gateway status
+openclaw gateway status
+```
+
+If ANI does not appear online after updating the config, reconnect or restart the OpenClaw gateway.
+
+## Configuration
+
+All settings live under `channels.ani` in your OpenClaw config.
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `serverUrl` | string | yes | -- | ANI server base URL (no trailing slash) |
+| `apiKey` | string | yes | -- | Permanent API key (`aim_` prefix). Legacy `aimb_` keys are rejected. |
+| `entityId` | number | no | auto-detected | Legacy numeric override. Usually leave empty. |
+| `enabled` | boolean | no | `true` | Enable/disable the channel |
+| `textChunkLimit` | number | no | `4000` | Max chars per outbound message chunk |
+| `dm.policy` | string | no | `"open"` | DM routing: `"open"` or `"disabled"` |
+| `name` | string | no | -- | Display name for status output |
+
+## How It Works
+
+**Inbound (ANI -> OpenClaw):** WebSocket connection to `/api/v1/ws`. On `message.new`, fetches conversation context (title, participants, memories), formats an agent envelope, dispatches through the reply pipeline. Revoked messages and cancelled streams are detected and aborted in-flight.
+
+**Outbound (OpenClaw -> ANI):** REST API `POST /api/v1/messages/send`. Parses `<artifact>` tags into structured content. Plain text chunked at markdown boundaries. Files uploaded via multipart then sent as attachments.
+
+**Authentication:** On startup, calls `GET /api/v1/me` to verify the API key and auto-discover bot identity. Only permanent keys (`aim_`) are accepted.
+
+## Task Roadmap Tools
+
+The ANI plugin can now read and mutate the current conversation task roadmap through dedicated tools:
+
+- `ani_list_conversation_tasks`
+- `ani_get_task`
+- `ani_create_task`
+- `ani_update_task`
+- `ani_delete_task`
+
+These tools reuse ANI's backend permissions:
+
+- the bot must be a member of the conversation
+- create/list/get require conversation participation
+- update/delete still follow ANI's existing creator / assignee / admin rules
+
+Planned but not implemented yet:
+
+- approval workflow for task mutations in group chats
+- member-submitted task edits entering a pending-review queue for group admins
+
+## Attachment Behavior
+
+This plugin now follows ANI's protected attachment model:
+
+- conversation files stay as protected ANI resources
+- the plugin downloads them with ANI auth
+- binary/media files are saved locally and passed via `MediaPath` / `MediaPaths`
+- small text files may be inlined into the model prompt
+- the plugin should not expose naked protected `/files/...` URLs to the agent as if they were public downloads
+
+Practical implication:
+
+- transport can succeed even if the model cannot truly understand the file contents
+- image/audio/video understanding still depends on the selected model/runtime
+- PDF / office docs are transport-supported, but parser experience is still incomplete
+
+Current support levels:
+
+- text files: most reliable, small files may be inlined for the model
+- images / audio / video: transport works, understanding still depends on the selected model/runtime
+- PDF / Office documents: transport works, parser experience is still incomplete
+
+If you need a fuller attachment capability breakdown, document it in your ANI deployment docs rather than relying on private local paths.
+
+## Multi-Agent Routing
+
+```yaml
+agents:
+  list:
+    - id: main
+      workspace: ~/.openclaw/workspace
+    - id: ops-agent
+      workspace: ~/.openclaw/workspace-ops
+
+bindings:
+  - agentId: ops-agent
+    match:
+      channel: ani
+      peer:
+        kind: channel
+        id: "2920436443328762"  # ANI conversation ID
+```
+
+Find conversation IDs in: ANI web URL bar, gateway logs (`ani: inbound conv=<id>`), or the bot's system prompt.
+
+## Limitations
+
+- **Single account** -- one ANI account per OpenClaw instance
+- **No threads** -- ANI uses a flat conversation model
+- **No polls** -- not supported by ANI
+- **Model-dependent multimodality** -- successful attachment delivery does not guarantee image/audio/video understanding
+
+## Development
+
+```bash
+# From OpenClaw repo root
+npx vitest run --config vitest.extensions.config.ts extensions/ani/
+```

package/index.ts

@@ -0,0 +1,45 @@
+import { emptyPluginConfigSchema, type OpenClawPluginApi } from "./src/sdk-compat.js";
+
+import { aniPlugin } from "./src/channel.js";
+import { setAniRuntime } from "./src/runtime.js";
+import {
+  createCreateTaskTool,
+  createDeleteTaskTool,
+  createGetHistoryTool,
+  createGetTaskTool,
+  createListTasksTool,
+  createSendFileTool,
+  createUpdateTaskTool,
+} from "./src/tools.js";
+// Tool names: ani_send_file, ani_fetch_chat_history_messages, ani_list_conversation_tasks, ani_get_task, ani_create_task, ani_update_task, ani_delete_task
+
+const plugin = {
+  id: "ani",
+  name: "Agent-Native IM",
+  description: "ANI Agent-Native IM channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setAniRuntime(api.runtime);
+    // Register tool via BOTH paths for maximum compatibility:
+    // 1. api.registerTool() — plugin tools path (resolvePluginTools)
+    // 2. agentTools on channel — channel tools path (listChannelAgentTools)
+    const sendFileTool = createSendFileTool();
+    const getHistoryTool = createGetHistoryTool();
+    const listTasksTool = createListTasksTool();
+    const getTaskTool = createGetTaskTool();
+    const createTaskTool = createCreateTaskTool();
+    const updateTaskTool = createUpdateTaskTool();
+    const deleteTaskTool = createDeleteTaskTool();
+    const tools = [sendFileTool, getHistoryTool, listTasksTool, getTaskTool, createTaskTool, updateTaskTool, deleteTaskTool];
+    api.registerTool(sendFileTool);
+    api.registerTool(getHistoryTool);
+    api.registerTool(listTasksTool);
+    api.registerTool(getTaskTool);
+    api.registerTool(createTaskTool);
+    api.registerTool(updateTaskTool);
+    api.registerTool(deleteTaskTool);
+    api.registerChannel({ plugin: { ...aniPlugin, agentTools: () => tools } });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,74 @@
+{
+  "id": "ani",
+  "channels": [
+    "ani"
+  ],
+  "uiHints": {
+    "serverUrl": {
+      "label": "Server URL",
+      "placeholder": "https://your-ani-server.example.com",
+      "help": "Base URL of the ANI server (no trailing slash)"
+    },
+    "apiKey": {
+      "label": "API Key",
+      "placeholder": "aim_...",
+      "sensitive": true,
+      "help": "Permanent ANI API key (aim_ prefix). Legacy aimb_ keys are not supported."
+    },
+    "entityId": {
+      "label": "Bot Entity ID",
+      "help": "Legacy numeric override. Usually leave empty and let ANI auto-detect.",
+      "advanced": true
+    },
+    "enabled": {
+      "label": "Enabled",
+      "help": "Enable or disable the ANI channel"
+    },
+    "textChunkLimit": {
+      "label": "Text Chunk Limit",
+      "help": "Max characters per outbound message chunk (default: 4000)",
+      "advanced": true
+    },
+    "dm.policy": {
+      "label": "DM Policy",
+      "help": "Direct message routing policy (open or disabled)",
+      "advanced": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "enabled": {
+        "type": "boolean"
+      },
+      "name": {
+        "type": "string"
+      },
+      "serverUrl": {
+        "type": "string"
+      },
+      "apiKey": {
+        "type": "string"
+      },
+      "entityId": {
+        "type": "number"
+      },
+      "dm": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "policy": {
+            "type": "string",
+            "enum": ["open", "disabled"]
+          }
+        }
+      },
+      "textChunkLimit": {
+        "type": "number",
+        "minimum": 100
+      }
+    },
+    "required": []
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@wzfukui/ani",
+  "version": "2026.3.28",
+  "type": "module",
+  "description": "ANI Agent-Native IM channel plugin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wzfukui/openclaw.git",
+    "directory": "extensions/ani"
+  },
+  "homepage": "https://github.com/wzfukui/openclaw/tree/main/extensions/ani",
+  "bugs": {
+    "url": "https://github.com/wzfukui/openclaw/issues"
+  },
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "src/channel.ts",
+    "src/config-schema.ts",
+    "src/monitor",
+    "src/outbound.ts",
+    "src/runtime.ts",
+    "src/sdk-compat.ts",
+    "src/tools.ts",
+    "src/types.ts",
+    "src/utils.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "ani",
+      "label": "Agent-Native IM",
+      "selectionLabel": "Agent-Native IM (ANI)",
+      "docsPath": "/channels/ani",
+      "docsLabel": "ani",
+      "blurb": "Agent-Native IM — messaging built for AI-first Bot collaboration.",
+      "order": 80,
+      "quickstartAllowFrom": false
+    },
+    "install": {
+      "npmSpec": "@wzfukui/ani",
+      "localPath": "extensions/ani",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.41",
+    "ws": "^8.18.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "devDependencies": {
+    "openclaw": "workspace:*",
+    "@types/ws": "^8.5.13"
+  }
+}

package/src/channel.ts

@@ -0,0 +1,242 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  setAccountEnabledInConfigSection,
+  deleteAccountFromConfigSection,
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  type ChannelPlugin,
+} from "./sdk-compat.js";
+
+import { AniConfigSchema } from "./config-schema.js";
+import type { CoreConfig, ResolvedAniAccount } from "./types.js";
+import { aniOutbound } from "./outbound.js";
+import { normalizeAniServerUrl } from "./utils.js";
+
+const meta = {
+  id: "ani",
+  label: "Agent-Native IM",
+  selectionLabel: "Agent-Native IM (plugin)",
+  docsPath: "/channels/ani",
+  docsLabel: "ani",
+  blurb: "Agent-Native IM — messaging platform built for AI Bots.",
+  order: 80,
+  quickstartAllowFrom: false,
+};
+
+export function resolveAniAccount(params: {
+  cfg: CoreConfig;
+  accountId?: string;
+}): ResolvedAniAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const aniCfg = params.cfg.channels?.ani ?? {};
+  const enabled = aniCfg.enabled !== false;
+  const serverUrl = normalizeAniServerUrl(aniCfg.serverUrl);
+  const apiKey = aniCfg.apiKey ?? "";
+  const configured = Boolean(serverUrl && apiKey && !apiKey.startsWith("aimb_"));
+
+  return {
+    accountId,
+    enabled,
+    name: aniCfg.name?.trim(),
+    configured,
+    serverUrl: serverUrl || undefined,
+    entityId: aniCfg.entityId,
+    config: aniCfg,
+  };
+}
+
+export const aniPlugin: ChannelPlugin<ResolvedAniAccount> = {
+  id: "ani",
+  meta,
+
+  capabilities: {
+    chatTypes: ["group", "direct"],
+    polls: false,
+    reactions: true,
+    threads: false,
+    media: true,
+  },
+
+  reload: { configPrefixes: ["channels.ani"] },
+  configSchema: buildChannelConfigSchema(AniConfigSchema),
+
+  config: {
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+    resolveAccount: (cfg, accountId) =>
+      resolveAniAccount({ cfg: cfg as CoreConfig, accountId }),
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: "ani",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: "ani",
+        accountId,
+        clearBaseFields: ["name", "serverUrl", "apiKey", "entityId"],
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.serverUrl,
+    }),
+  },
+
+  security: {
+    resolveDmPolicy: ({ account }) => ({
+      policy: account.config.dm?.policy ?? "open",
+      allowFrom: [],
+      policyPath: "channels.ani.dm.policy",
+      allowFromPath: "channels.ani.dm.allowFrom",
+    }),
+  },
+
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg: cfg as CoreConfig,
+        channelKey: "ani",
+        accountId,
+        name,
+      }),
+    validateInput: ({ input }) => {
+      if (input.useEnv) return null;
+      if (!input.serverUrl?.trim()) return "ANI requires --server-url";
+      if (!input.apiKey?.trim()) return "ANI requires --api-key (permanent aim_ key)";
+      const key = input.apiKey?.trim() ?? "";
+      if (key.startsWith("aimb_")) {
+        return "ANI requires a permanent key (aim_ prefix). Legacy aimb_ keys are no longer supported.";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, input }) => {
+      const named = applyAccountNameToChannelSection({
+        cfg: cfg as CoreConfig,
+        channelKey: "ani",
+        accountId: DEFAULT_ACCOUNT_ID,
+        name: input.name,
+      });
+      if (input.useEnv) {
+        return {
+          ...named,
+          channels: {
+            ...named.channels,
+            ani: { ...named.channels?.ani, enabled: true },
+          },
+        } as CoreConfig;
+      }
+      const existing = (named as CoreConfig).channels?.ani ?? {};
+      return {
+        ...named,
+        channels: {
+          ...named.channels,
+          ani: {
+            ...existing,
+            enabled: true,
+            ...(input.serverUrl ? { serverUrl: input.serverUrl.trim().replace(/\/+$/, "") } : {}),
+            ...(input.apiKey ? { apiKey: input.apiKey.trim() } : {}),
+          },
+        },
+      } as CoreConfig;
+    },
+  },
+
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+  },
+
+  outbound: aniOutbound,
+
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((account) => {
+        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
+        if (!lastError) return [];
+        return [
+          {
+            channel: "ani",
+            accountId: account.accountId,
+            kind: "runtime",
+            message: `Channel error: ${lastError}`,
+          },
+        ];
+      }),
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      baseUrl: snapshot.baseUrl ?? null,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+    }),
+    probeAccount: async ({ account }) => {
+      if (!account.serverUrl || !account.config.apiKey) {
+        return { ok: false, error: "not configured", elapsedMs: 0 };
+      }
+      const start = Date.now();
+      try {
+        const { verifyAniConnection } = await import("./monitor/send.js");
+        await verifyAniConnection({
+          serverUrl: account.serverUrl,
+          apiKey: account.config.apiKey,
+        });
+        return { ok: true, elapsedMs: Date.now() - start };
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+          elapsedMs: Date.now() - start,
+        };
+      }
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.serverUrl,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      probe,
+      lastProbeAt: runtime?.lastProbeAt ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({
+        accountId: account.accountId,
+        baseUrl: account.serverUrl,
+      });
+      ctx.log?.info(`[${account.accountId}] starting ANI provider (${account.serverUrl ?? "ani"})`);
+      const { monitorAniProvider } = await import("./monitor/index.js");
+      return monitorAniProvider({
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        accountId: account.accountId,
+      });
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+export const AniConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  name: z.string().optional(),
+  serverUrl: z.string().optional(),
+  apiKey: z.string().optional(),
+  entityId: z.number().optional(),
+  dm: z
+    .object({
+      policy: z.enum(["open", "disabled"]).optional(),
+    })
+    .optional(),
+  textChunkLimit: z.number().optional(),
+});

package/src/monitor/debounce.ts

@@ -0,0 +1,68 @@
+/**
+ * Inbound message debouncer: coalesces rapid messages from the same sender
+ * in the same conversation before dispatching to the AI agent.
+ *
+ * This prevents wasted tokens when a user sends multiple messages in quick
+ * succession (e.g., 3 messages in 2 seconds) — each would otherwise trigger
+ * a separate AI dispatch.
+ */
+
+export type PendingMessage = { text: string; messageId: string };
+
+export type DebouncerEntry = {
+  timer: ReturnType<typeof setTimeout>;
+  messages: PendingMessage[];
+};
+
+export function createInboundDebouncer(delayMs: number = 1500) {
+  const pending = new Map<string, DebouncerEntry>();
+
+  return {
+    /**
+     * Queue a message for debounced dispatch.
+     * @param key - Unique key, typically `${conversationId}:${senderId}`
+     * @param text - Message text
+     * @param messageId - Original message ID
+     * @param dispatch - Called after the debounce window with combined text and all message IDs
+     */
+    debounce(
+      key: string,
+      text: string,
+      messageId: string,
+      dispatch: (combinedText: string, messageIds: string[]) => void,
+    ) {
+      const entry = pending.get(key);
+      if (entry) {
+        clearTimeout(entry.timer);
+        entry.messages.push({ text, messageId });
+      } else {
+        pending.set(key, {
+          timer: null as unknown as ReturnType<typeof setTimeout>,
+          messages: [{ text, messageId }],
+        });
+      }
+      const e = pending.get(key)!;
+      e.timer = setTimeout(() => {
+        pending.delete(key);
+        dispatch(
+          e.messages.map((m) => m.text).join("\n"),
+          e.messages.map((m) => m.messageId),
+        );
+      }, delayMs);
+    },
+
+    /** Cancel and remove a pending debounce entry. */
+    clear(key: string) {
+      const entry = pending.get(key);
+      if (entry) {
+        clearTimeout(entry.timer);
+        pending.delete(key);
+      }
+    },
+
+    /** Number of pending debounce entries (for testing/monitoring). */
+    get size() {
+      return pending.size;
+    },
+  };
+}