@vama/openclaw 2026.5.5-4 → 2026.5.5-6

package/src/bot.ts

@@ -0,0 +1,345 @@
+import { resolveVamaAccount } from "./accounts.js";
+import { tryRecordMessagePersistent } from "./dedup.js";
+import { dispatchStarted, dispatchEnded } from "./fc-keepalive.js";
+import type { ClawdbotConfig, RuntimeEnv } from "./host-sdk.js";
+import { createScopedPairingAccess } from "./host-sdk.js";
+import { createVamaReplyDispatcher } from "./reply-dispatcher.js";
+import { getVamaRuntime } from "./runtime.js";
+import { sendMessageVama } from "./send.js";
+import type { VamaAttachment, VamaMessageEvent } from "./types.js";
+
+/**
+ * Per-attachment fetch ceiling. Mirrors the limit `core.channel.media`
+ * already enforces internally on most provider channels (Telegram /
+ * WhatsApp / Zalo); kept explicit here so the ceiling is visible at the
+ * call site and can be surfaced later as a config knob without changing
+ * the `core` API contract.
+ */
+const VAMA_ATTACHMENT_MAX_BYTES = 25 * 1024 * 1024;
+
+export async function handleVamaMessage(params: {
+  cfg: ClawdbotConfig;
+  event: VamaMessageEvent;
+  runtime?: RuntimeEnv;
+  accountId?: string;
+  /**
+   * Optional replay marker forwarded by the OCC api when the Stripe
+   * webhook re-delivers a user message that was stashed mid-flight
+   * (vama-billing-model-2026 replay-on-payment). When set, we bypass
+   * the message-id dedup gate so the original prompt is re-dispatched
+   * against the now-replenished wallet — without this, the message_id
+   * matches the prior delivery and `tryRecordMessagePersistent` filters
+   * the replay as a duplicate, leaving the user's prompt unanswered.
+   * Value is `pi_<paymentIntentId>`; opaque to this plugin.
+   */
+  replayId?: string;
+}): Promise<void> {
+  const { cfg, event, runtime, accountId, replayId } = params;
+  const account = resolveVamaAccount({ cfg, accountId });
+  const vamaCfg = account.config;
+
+  const log = runtime?.log ?? console.log;
+  const error = runtime?.error ?? console.error;
+
+  // Dedup check — skipped on replay so the user's pending prompt actually
+  // re-dispatches after a top-up (the OCC api forwards x-replay-id on
+  // post-payment loopbacks; see `apps/api/src/routes/vama-webhook.ts`).
+  if (replayId) {
+    log(
+      `vama[${account.accountId}]: replay (${replayId}) — bypassing dedup for ${event.message_id}`,
+    );
+  } else if (!(await tryRecordMessagePersistent(event.message_id, account.accountId, log))) {
+    log(`vama: skipping duplicate message ${event.message_id}`);
+    return;
+  }
+
+  const senderId = event.sender_id;
+  const senderName = event.sender_name ?? senderId;
+  const text = event.text ?? "";
+  const channelId = event.channel_id;
+  const messageId = event.message_id;
+  const parentId = event.parent_id;
+  const parentText =
+    typeof event.parent_text === "string" && event.parent_text.trim().length > 0
+      ? event.parent_text
+      : undefined;
+  const parentSenderName =
+    typeof event.parent_sender_name === "string" && event.parent_sender_name.trim().length > 0
+      ? event.parent_sender_name
+      : undefined;
+  const parentSenderId =
+    typeof event.parent_sender_id === "string" && event.parent_sender_id.trim().length > 0
+      ? event.parent_sender_id
+      : undefined;
+  const parentSender = parentSenderName ?? parentSenderId;
+  // BotHub forwards inbound media as an `attachments` array (one entry
+  // per file the user uploaded). Filter to attachments with a usable
+  // URL so we don't spend a fetch round-trip on malformed payloads.
+  const attachments: VamaAttachment[] = Array.isArray(event.attachments)
+    ? event.attachments.filter(
+        (a): a is VamaAttachment => Boolean(a) && typeof a.url === "string" && a.url.length > 0,
+      )
+    : [];
+  const parentAttachments: VamaAttachment[] = Array.isArray(event.parent_attachments)
+    ? event.parent_attachments.filter(
+        (a): a is VamaAttachment => Boolean(a) && typeof a.url === "string" && a.url.length > 0,
+      )
+    : [];
+
+  // Attachments-only messages (e.g. user sends a photo with no caption)
+  // arrive with `text=""`. Don't drop them — multimodal LLMs can answer
+  // off the image alone.
+  if (!text.trim() && attachments.length === 0) {
+    log(`vama[${account.accountId}]: ignoring empty message ${messageId}`);
+    return;
+  }
+
+  log(`vama[${account.accountId}]: received message from ${senderId} in ${channelId}`);
+
+  try {
+    const core = getVamaRuntime();
+
+    // DM policy check
+    const dmPolicy = vamaCfg?.dmPolicy ?? "open";
+    const configAllowFrom = (vamaCfg?.allowFrom ?? []).map((e) => String(e));
+    const useAccessGroups = cfg.commands?.useAccessGroups !== false;
+
+    const pairing = createScopedPairingAccess({
+      core,
+      channel: "vama",
+      accountId: account.accountId,
+    });
+
+    const shouldComputeCommandAuthorized = core.channel.commands.shouldComputeCommandAuthorized(
+      text,
+      cfg,
+    );
+    const storeAllowFrom =
+      dmPolicy !== "allowlist" && (dmPolicy !== "open" || shouldComputeCommandAuthorized)
+        ? await pairing.readAllowFromStore().catch(() => [])
+        : [];
+    const effectiveDmAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+    const dmAllowed =
+      dmPolicy === "open"
+        ? effectiveDmAllowFrom.length === 0 || effectiveDmAllowFrom.includes(senderId)
+        : effectiveDmAllowFrom.includes(senderId);
+
+    if (dmPolicy !== "open" && !dmAllowed) {
+      if (dmPolicy === "pairing") {
+        const { code, created } = await pairing.upsertPairingRequest({
+          id: senderId,
+          meta: { name: senderName },
+        });
+        if (created) {
+          log(`vama[${account.accountId}]: pairing request sender=${senderId}`);
+          try {
+            await sendMessageVama({
+              cfg,
+              to: channelId,
+              text: core.channel.pairing.buildPairingReply({
+                channel: "vama",
+                idLine: `Your Vama user id: ${senderId}`,
+                code,
+              }),
+              accountId: account.accountId,
+            });
+          } catch (err) {
+            log(`vama[${account.accountId}]: pairing reply failed for ${senderId}: ${String(err)}`);
+          }
+        }
+      } else {
+        log(
+          `vama[${account.accountId}]: blocked unauthorized sender ${senderId} (dmPolicy=${dmPolicy})`,
+        );
+      }
+      return;
+    }
+
+    const commandAllowFrom = effectiveDmAllowFrom;
+    const senderAllowedForCommands =
+      commandAllowFrom.length === 0 || commandAllowFrom.includes(senderId);
+    const commandAuthorized = shouldComputeCommandAuthorized
+      ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+          useAccessGroups,
+          authorizers: [
+            { configured: commandAllowFrom.length > 0, allowed: senderAllowedForCommands },
+          ],
+        })
+      : undefined;
+
+    const vamaFrom = `vama:${senderId}`;
+    const vamaTo = `channel:${channelId}`;
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "vama",
+      accountId: account.accountId,
+      peer: {
+        kind: "direct",
+        id: senderId,
+      },
+    });
+
+    const preview = text.replace(/\s+/g, " ").slice(0, 160);
+    core.system.enqueueSystemEvent(`Vama[${account.accountId}] DM from ${senderName}: ${preview}`, {
+      sessionKey: route.sessionKey,
+      contextKey: `vama:message:${channelId}:${messageId}`,
+    });
+
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+    const messageBody = `${senderName}: ${text}`;
+    const body = core.channel.reply.formatAgentEnvelope({
+      channel: "Vama",
+      from: senderId,
+      timestamp: new Date(),
+      envelope: envelopeOptions,
+      body: messageBody,
+    });
+
+    // On replay, suffix MessageSid with the replay marker so the openclaw
+    // SDK's in-process inbound-dedupe cache (auto-reply/reply/inbound-dedupe.ts,
+    // 20-min TTL keyed on provider|account|session|peer|thread|messageId) sees
+    // a fresh key. Bypassing only the persistent message-id dedup at the top
+    // of this handler isn't enough — the SDK has its own in-memory gate that
+    // also fires on identical inbound ids, returning queuedFinal=false in
+    // ~3ms and leaving the user's pending prompt unanswered post-top-up.
+    // Vama uses UUID message ids (non-numeric), so the abort-cutoff path's
+    // numeric MessageSid comparator is unaffected.
+    const dispatchMessageSid = replayId ? `${messageId}#replay-${replayId.slice(-12)}` : messageId;
+
+    // Resolve attachment URLs into local files before we hand control to
+    // the agent runtime. `core.channel.media.fetchRemoteMedia` performs
+    // the HTTP fetch with SSRF / size guards, then `saveMediaBuffer`
+    // persists the bytes under `<media-dir>/inbound/<uuid>` and returns
+    // the absolute path. `finalizeInboundContext` reads MediaPaths /
+    // MediaUrls / MediaTypes (or the singular variants) to construct
+    // multimodal LLM content blocks — same path Telegram and Zalo
+    // already use for inbound media. Per-attachment failures are
+    // logged and skipped: text-only fallback is preferable to dropping
+    // the whole message.
+    const fetchAttachments = async (items: VamaAttachment[], label: string) => {
+      const resolved: { path: string; contentType?: string }[] = [];
+      for (const attachment of items) {
+        try {
+          const fetched = await core.channel.media.fetchRemoteMedia({
+            url: attachment.url,
+            maxBytes: VAMA_ATTACHMENT_MAX_BYTES,
+          });
+          const saved = await core.channel.media.saveMediaBuffer(
+            fetched.buffer,
+            fetched.contentType,
+            "inbound",
+            VAMA_ATTACHMENT_MAX_BYTES,
+          );
+          resolved.push({ path: saved.path, contentType: saved.contentType });
+        } catch (err) {
+          error(
+            `vama[${account.accountId}]: failed to fetch ${label} ${attachment.url}: ${String(err)}`,
+          );
+        }
+      }
+      return resolved;
+    };
+
+    const resolvedCurrentMedia = await fetchAttachments(attachments, "attachment");
+    const resolvedParentMedia = await fetchAttachments(
+      parentAttachments,
+      "reply-target attachment",
+    );
+    const resolvedMedia = [...resolvedCurrentMedia, ...resolvedParentMedia];
+    const mediaPaths = resolvedMedia.map((m) => m.path);
+    const mediaTypes = resolvedMedia
+      .map((m) => m.contentType)
+      .filter((value): value is string => typeof value === "string" && value.length > 0);
+    const replyTargetMediaNote =
+      resolvedParentMedia.length > 0
+        ? `[reply target media attachments included as additional media inputs: ${resolvedParentMedia.length}]`
+        : undefined;
+    const replyToBody =
+      parentText && replyTargetMediaNote
+        ? `${parentText}\n\n${replyTargetMediaNote}`
+        : (parentText ?? replyTargetMediaNote);
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: body,
+      BodyForAgent: messageBody,
+      RawBody: text,
+      CommandBody: text,
+      From: vamaFrom,
+      To: vamaTo,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: "direct",
+      SenderName: senderName,
+      SenderId: senderId,
+      Provider: "vama" as const,
+      Surface: "vama" as const,
+      MessageSid: dispatchMessageSid,
+      ReplyToId: parentId,
+      ReplyToBody: replyToBody,
+      ReplyToSender: parentSender,
+      ReplyToIsQuote: replyToBody ? true : undefined,
+      Timestamp: Date.now(),
+      CommandAuthorized: commandAuthorized,
+      OriginatingChannel: "vama" as const,
+      OriginatingTo: vamaTo,
+      // First-item singular keys preserved for older agent-runtime
+      // builds; full lists for the multimodal-content-block path.
+      // `finalizeInboundContext` itself pads MediaTypes to match
+      // MediaPaths length and supplies a default MIME if missing.
+      MediaPath: mediaPaths[0],
+      MediaType: mediaTypes[0],
+      MediaUrl: mediaPaths[0],
+      MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
+      MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
+      MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
+    });
+
+    const { dispatcher, replyOptions, markDispatchIdle } = createVamaReplyDispatcher({
+      cfg,
+      agentId: route.agentId,
+      runtime,
+      channelId,
+      replyToMessageId: parentId,
+      accountId: account.accountId,
+    });
+
+    log(`vama[${account.accountId}]: dispatching to agent (session=${route.sessionKey})`);
+    // Bracket the dispatch with FC keepalive so vmctl's idle-pauser
+    // doesn't snapshot the VM mid-tool-call. See fc-keepalive.ts for
+    // the rationale (it's a no-op outside FC).
+    //
+    // dispatchStarted() goes inside the try so that if it ever throws
+    // synchronously (it shouldn't — it only mutates module state and
+    // schedules a timer — but this is a counter-leak failsafe), the
+    // counter doesn't get stuck at >0 with no matching dispatchEnded.
+    let keepaliveActive = false;
+    try {
+      dispatchStarted();
+      keepaliveActive = true;
+      const { queuedFinal, counts } = await core.channel.reply.withReplyDispatcher({
+        dispatcher,
+        onSettled: () => {
+          markDispatchIdle();
+        },
+        run: () =>
+          core.channel.reply.dispatchReplyFromConfig({
+            ctx: ctxPayload,
+            cfg,
+            dispatcher,
+            replyOptions,
+          }),
+      });
+
+      log(
+        `vama[${account.accountId}]: dispatch complete (queuedFinal=${queuedFinal}, replies=${counts.final})`,
+      );
+    } finally {
+      if (keepaliveActive) {
+        dispatchEnded();
+      }
+    }
+  } catch (err) {
+    error(`vama[${account.accountId}]: failed to dispatch message: ${String(err)}`);
+  }
+}

package/src/channel-actions.test.ts

@@ -0,0 +1,289 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk/vama";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const sendMessageVamaMock = vi.hoisted(() => vi.fn());
+const sendFileMock = vi.hoisted(() => vi.fn());
+const createBotHubClientMock = vi.hoisted(() =>
+  vi.fn(() => ({
+    sendFile: sendFileMock,
+  })),
+);
+
+vi.mock("./send.js", () => ({
+  sendMessageVama: sendMessageVamaMock,
+}));
+
+vi.mock("./client.js", async (importOriginal) => {
+  const mod = await importOriginal<typeof import("./client.js")>();
+  return {
+    ...mod,
+    createBotHubClient: createBotHubClientMock,
+  };
+});
+
+import { vamaMessageActions } from "./channel-actions.js";
+
+function makeCfg(vama?: Record<string, unknown>): ClawdbotConfig {
+  return { channels: { vama } } as ClawdbotConfig;
+}
+
+const CONFIGURED_CFG = makeCfg({ enabled: true, botToken: "tok", bothubUrl: "https://b.example" });
+const UNCONFIGURED_CFG = makeCfg({ enabled: true });
+
+describe("vamaMessageActions", () => {
+  beforeEach(() => {
+    sendMessageVamaMock.mockReset().mockResolvedValue({
+      messageId: "msg-text-123",
+      channelId: "chan-1",
+    });
+    sendFileMock.mockReset().mockResolvedValue({
+      message_id: "msg-file-456",
+      channel_id: "chan-1",
+    });
+    createBotHubClientMock.mockClear();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("describeMessageTool", () => {
+    it("exposes `send` when account is configured", () => {
+      const discovery = vamaMessageActions.describeMessageTool({
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      });
+      expect(discovery?.actions).toContain("send");
+    });
+
+    it("returns empty actions when account is not configured", () => {
+      const discovery = vamaMessageActions.describeMessageTool({
+        cfg: UNCONFIGURED_CFG,
+        accountId: "default",
+      });
+      expect(discovery?.actions ?? []).toEqual([]);
+    });
+
+    it("declares no extra capabilities (no presentations/buttons/polls/etc)", () => {
+      const discovery = vamaMessageActions.describeMessageTool({
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      });
+      expect(discovery?.capabilities ?? []).toEqual([]);
+      expect(discovery?.schema ?? null).toBeNull();
+    });
+  });
+
+  describe("resolveExecutionMode", () => {
+    it("always runs in the gateway", () => {
+      for (const action of ["send"] as const) {
+        expect(vamaMessageActions.resolveExecutionMode?.({ action })).toBe("gateway");
+      }
+    });
+  });
+
+  describe("extractToolSend", () => {
+    it("extracts target when action is `send`", () => {
+      const send = vamaMessageActions.extractToolSend?.({
+        args: { action: "send", to: "chan-1" },
+      });
+      expect(send).toMatchObject({ to: "chan-1" });
+    });
+
+    it("returns null for non-send actions", () => {
+      const send = vamaMessageActions.extractToolSend?.({
+        args: { action: "react", to: "chan-1" },
+      });
+      expect(send).toBeNull();
+    });
+  });
+
+  describe("handleAction", () => {
+    it("rejects non-send actions", async () => {
+      await expect(
+        vamaMessageActions.handleAction!({
+          channel: "vama",
+          action: "react",
+          params: { to: "chan-1" },
+          cfg: CONFIGURED_CFG,
+          accountId: "default",
+        } as never),
+      ).rejects.toThrow(/Unsupported Vama action: react/);
+    });
+
+    it("rejects sends when account is not configured", async () => {
+      await expect(
+        vamaMessageActions.handleAction!({
+          channel: "vama",
+          action: "send",
+          params: { to: "chan-1", caption: "hi" },
+          cfg: UNCONFIGURED_CFG,
+          accountId: "default",
+        } as never),
+      ).rejects.toThrow(/not configured/);
+    });
+
+    it("text-only sends go through sendMessageVama and return a jsonResult", async () => {
+      const result = await vamaMessageActions.handleAction!({
+        channel: "vama",
+        action: "send",
+        params: { to: "chan-1", caption: "hello world" },
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      } as never);
+
+      expect(sendMessageVamaMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          to: "chan-1",
+          text: "hello world",
+          accountId: "default",
+        }),
+      );
+      expect(sendFileMock).not.toHaveBeenCalled();
+      // The tool result is text-encoded JSON (jsonResult) — assert the
+      // shape via the embedded `details` payload that openclaw attaches.
+      const details = (result as { details?: { ok?: boolean; messageId?: string } }).details;
+      expect(details).toMatchObject({
+        ok: true,
+        messageId: "msg-text-123",
+        channelId: "chan-1",
+      });
+    });
+
+    it("local-path media sends go through client.sendFile", async () => {
+      const result = await vamaMessageActions.handleAction!({
+        channel: "vama",
+        action: "send",
+        params: {
+          to: "chan-1",
+          media: "/home/app/.openclaw/workspace/paper.html",
+          caption: "Here you go",
+        },
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      } as never);
+
+      expect(createBotHubClientMock).toHaveBeenCalled();
+      expect(sendFileMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          channelId: "chan-1",
+          path: "/home/app/.openclaw/workspace/paper.html",
+          caption: "Here you go",
+          // `.html` maps to the catch-all "file" attachment hint.
+          attachmentType: "file",
+        }),
+      );
+      expect(sendMessageVamaMock).not.toHaveBeenCalled();
+      const details = (result as { details?: { messageId?: string } }).details;
+      expect(details).toMatchObject({
+        ok: true,
+        messageId: "msg-file-456",
+      });
+    });
+
+    it.each([
+      { name: "media", body: { media: "/work/a.png" } },
+      { name: "path", body: { path: "/work/a.png" } },
+      { name: "filePath", body: { filePath: "/work/a.png" } },
+    ])("accepts `$name` as the media field alias", async ({ body }) => {
+      await vamaMessageActions.handleAction!({
+        channel: "vama",
+        action: "send",
+        params: { to: "chan-1", ...body },
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      } as never);
+
+      expect(sendFileMock).toHaveBeenCalledWith(
+        expect.objectContaining({ path: "/work/a.png", attachmentType: "image" }),
+      );
+    });
+
+    it.each([
+      { name: "to", body: { to: "chan-1" } },
+      { name: "channelId", body: { channelId: "chan-1" } },
+      { name: "target", body: { target: "chan-1" } },
+    ])("accepts `$name` as the channel target alias", async ({ body }) => {
+      await vamaMessageActions.handleAction!({
+        channel: "vama",
+        action: "send",
+        params: { ...body, caption: "hi" },
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      } as never);
+
+      expect(sendMessageVamaMock).toHaveBeenCalledWith(
+        expect.objectContaining({ to: "chan-1", text: "hi" }),
+      );
+    });
+
+    it("remote https URLs fall back to sending the link as text", async () => {
+      const result = await vamaMessageActions.handleAction!({
+        channel: "vama",
+        action: "send",
+        params: {
+          to: "chan-1",
+          media: "https://example.com/image.jpg",
+          caption: "look at this",
+        },
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      } as never);
+
+      expect(sendFileMock).not.toHaveBeenCalled();
+      expect(sendMessageVamaMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          to: "chan-1",
+          text: "look at this\nhttps://example.com/image.jpg",
+        }),
+      );
+      const details = (result as { details?: { warning?: string } }).details;
+      expect(details?.warning).toBe("remote_media_unsupported_sent_as_link");
+    });
+
+    it("file:// URLs are unwrapped to a local path", async () => {
+      await vamaMessageActions.handleAction!({
+        channel: "vama",
+        action: "send",
+        params: {
+          to: "chan-1",
+          media: "file:///work/scratch.txt",
+        },
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      } as never);
+
+      expect(sendFileMock).toHaveBeenCalledWith(
+        expect.objectContaining({ path: "/work/scratch.txt" }),
+      );
+    });
+
+    it("forwards replyTo as parentId on text sends", async () => {
+      await vamaMessageActions.handleAction!({
+        channel: "vama",
+        action: "send",
+        params: { to: "chan-1", caption: "thread reply", replyTo: "msg-99" },
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      } as never);
+
+      expect(sendMessageVamaMock).toHaveBeenCalledWith(
+        expect.objectContaining({ parentId: "msg-99" }),
+      );
+    });
+
+    it("forwards replyTo as parentId on file sends", async () => {
+      await vamaMessageActions.handleAction!({
+        channel: "vama",
+        action: "send",
+        params: { to: "chan-1", media: "/work/a.pdf", replyTo: "msg-100" },
+        cfg: CONFIGURED_CFG,
+        accountId: "default",
+      } as never);
+
+      expect(sendFileMock).toHaveBeenCalledWith(
+        expect.objectContaining({ parentId: "msg-100", attachmentType: "file" }),
+      );
+    });
+  });
+});