@vama/openclaw 2026.5.5-4 → 2026.5.5-6

package/src/channel-actions.ts

@@ -0,0 +1,242 @@
+import {
+  jsonResult,
+  readStringOrNumberParam,
+  readStringParam,
+} from "openclaw/plugin-sdk/channel-actions";
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+  ChannelMessageToolDiscovery,
+} from "openclaw/plugin-sdk/channel-contract";
+import { extractToolSend } from "openclaw/plugin-sdk/tool-send";
+import { resolveVamaAccount } from "./accounts.js";
+import { attachmentHintFromExtension, createBotHubClient } from "./client.js";
+import { sendMessageVama } from "./send.js";
+
+/**
+ * Channel-actions adapter for the shared `message` agent tool.
+ *
+ * Vama bots previously had exactly one outbound-media mechanism: emit a
+ * `MEDIA:/path/to/file` line inside the assistant reply text, which
+ * `reply-dispatcher.ts` parses out and uploads via `client.sendFile`. That
+ * path still works (see `reply-dispatcher.ts:parseInlineMediaTargets`) and
+ * remains the default for normal turn replies — but it is brittle:
+ *
+ * - The model has to remember the exact format (line-start `MEDIA:` + path)
+ * - Code-fenced or quoted variants don't match the line-anchored regex
+ * - Long-context decay degrades format-directive following more than
+ *   tool-call adherence on every frontier model
+ * - There is no schema validation; mistakes silently become text replies
+ *
+ * Registering a `ChannelMessageActionAdapter` here mirrors the pattern used
+ * by every other multimedia channel in openclaw (telegram, discord,
+ * matrix, etc.). It exposes a structured `message({action: "send", to:
+ * "<channelId>", media: "/path/to/file.html", caption: "..."})` tool call.
+ * The platform's `message-action-discovery` layer picks this up and
+ * publishes the right schema fragments on the agent's `message` tool. The
+ * model now has two paths:
+ *
+ *   1. (Preferred) Call the `message` tool with `media`/`path`/`filePath`
+ *      — schema-validated, returns a typed `{messageId, channelId}` tool
+ *      result the model can read.
+ *   2. (Fallback) Emit `MEDIA:/path` in plain text — `reply-dispatcher`
+ *      still parses it.
+ *
+ * Both paths converge on the same `client.sendFile` underneath and the
+ * same BotHub `POST /v1/bot/messages/file` endpoint. Existing dedup,
+ * filename preservation, and attachment-hint inference are unchanged.
+ */
+
+/**
+ * Extension-only file-extension helper. Duplicated from `outbound.ts` and
+ * `reply-dispatcher.ts` rather than factored out — those copies are
+ * intentionally narrow (basename-of-path slice, no normalisation) and we
+ * want this adapter to behave identically. If a future refactor centralises
+ * extension parsing in the plugin-SDK, all three sites can collapse.
+ */
+function extensionOf(path: string): string {
+  const idx = path.lastIndexOf(".");
+  if (idx < 0 || idx === path.length - 1) {
+    return "";
+  }
+  const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  if (idx < slash) {
+    return "";
+  }
+  return path.slice(idx + 1).toLowerCase();
+}
+
+/**
+ * Resolve a media argument (typically the `media`, `path`, or `filePath`
+ * field of the tool call) to a local filesystem path that
+ * `BotHubClient.sendFile` can read. Mirrors `localPathFromMediaUrl` in
+ * `outbound.ts` and `reply-dispatcher.ts` so all three Vama outbound
+ * paths agree on which inputs count as "uploadable from disk".
+ *
+ * Remote URLs (`http://` / `https://`) return `null` — the outbound side
+ * doesn't fetch remote bytes yet (no SSRF guard, no allowlist), so the
+ * caller falls back to sending the URL inline as text. That matches the
+ * fallback `outbound.ts:sendMedia` already implements.
+ */
+function localPathFromMediaArg(raw: string): string | null {
+  if (raw.startsWith("file://")) {
+    return raw.slice("file://".length);
+  }
+  if (raw.startsWith("/") || raw.startsWith("./")) {
+    return raw;
+  }
+  return null;
+}
+
+function describeVamaMessageTool({
+  cfg,
+  accountId,
+}: Parameters<
+  NonNullable<ChannelMessageActionAdapter["describeMessageTool"]>
+>[0]): ChannelMessageToolDiscovery {
+  // The tool-builder treats an empty `actions` list as "channel
+  // unavailable for this turn", which is what we want when the account
+  // has no botToken/bothubUrl: better to hide the tool than to expose
+  // it and have every call error at handleAction time.
+  const account = resolveVamaAccount({ cfg, accountId: accountId ?? undefined });
+  if (!account.configured) {
+    return { actions: [], capabilities: [], schema: null };
+  }
+  const actions: ChannelMessageActionName[] = ["send"];
+  return {
+    actions,
+    capabilities: [],
+    schema: null,
+  };
+}
+
+/**
+ * Read the channel/conversation target from the tool params. The model can
+ * supply any of `to` / `channelId` / `target` (the last is the routing
+ * schema's canonical name). Accept all three so a structured caller can
+ * use whichever maps best to their context.
+ */
+function readVamaTarget(params: Record<string, unknown>): string {
+  const value =
+    readStringOrNumberParam(params, "to") ??
+    readStringOrNumberParam(params, "channelId") ??
+    readStringOrNumberParam(params, "target", { required: true });
+  if (!value) {
+    throw new Error("Vama send: target channel id required (use `to` or `channelId`)");
+  }
+  return value;
+}
+
+/**
+ * Read the media argument the model supplied. The shared message tool
+ * exposes three optional fields that can carry an attachment path: `media`
+ * is openclaw's canonical name, `path` and `filePath` are the
+ * historical aliases. Accept all three so we don't second-guess which
+ * name the model picks.
+ */
+function readVamaMediaArg(params: Record<string, unknown>): string | undefined {
+  return (
+    readStringParam(params, "media") ??
+    readStringParam(params, "path") ??
+    readStringParam(params, "filePath")
+  );
+}
+
+function readVamaCaption(params: Record<string, unknown>): string | undefined {
+  // `caption` matches Telegram's convention; `message` matches the
+  // shared message tool's primary text slot. Either is fine — we use
+  // whichever was provided as the text body of the outbound send.
+  return readStringParam(params, "caption") ?? readStringParam(params, "message");
+}
+
+function readVamaParentId(params: Record<string, unknown>): string | undefined {
+  return (
+    readStringOrNumberParam(params, "replyTo") ??
+    readStringOrNumberParam(params, "replyToMessageId") ??
+    readStringOrNumberParam(params, "parentId")
+  );
+}
+
+export const vamaMessageActions: ChannelMessageActionAdapter = {
+  describeMessageTool: describeVamaMessageTool,
+  resolveExecutionMode: () => "gateway",
+  extractToolSend: ({ args }) => extractToolSend(args, "send"),
+  handleAction: async ({ action, params, cfg, accountId }) => {
+    if (action !== "send") {
+      throw new Error(`Unsupported Vama action: ${action}`);
+    }
+    const account = resolveVamaAccount({ cfg, accountId: accountId ?? undefined });
+    if (!account.configured) {
+      throw new Error(`Vama account "${account.accountId}" not configured`);
+    }
+
+    const to = readVamaTarget(params);
+    const mediaArg = readVamaMediaArg(params);
+    const caption = readVamaCaption(params);
+    const parentId = readVamaParentId(params);
+
+    if (!mediaArg) {
+      // Text-only send. Caption (or `message`) is the body.
+      const result = await sendMessageVama({
+        cfg,
+        to,
+        text: caption ?? "",
+        accountId: account.accountId,
+        parentId,
+      });
+      return jsonResult({
+        ok: true,
+        messageId: result.messageId,
+        channelId: result.channelId,
+      });
+    }
+
+    const localPath = localPathFromMediaArg(mediaArg);
+    if (!localPath) {
+      // Remote URL: outbound side can't fetch remote bytes safely yet
+      // (no SSRF guard, no allowlist). Fall back to sending the URL
+      // inline as text so the user at least gets a clickable link.
+      // Surfacing `warning` in the tool result tells the agent its
+      // attempt was downgraded — useful when the model decides whether
+      // to retry with a local path.
+      const text = caption?.trim() ? `${caption.trim()}\n${mediaArg}` : mediaArg;
+      const result = await sendMessageVama({
+        cfg,
+        to,
+        text,
+        accountId: account.accountId,
+        parentId,
+      });
+      return jsonResult({
+        ok: true,
+        messageId: result.messageId,
+        channelId: result.channelId,
+        warning: "remote_media_unsupported_sent_as_link",
+      });
+    }
+
+    // Local workspace artefact — upload via BotHub multipart endpoint.
+    // Note on sandbox enforcement: `mediaLocalRoots` IS available on the
+    // action context and Telegram threads it into `loadWebMedia` for
+    // sandbox-rooted reads. We deliberately don't enforce it here yet:
+    // the parallel `MEDIA:` inline-directive path in
+    // `reply-dispatcher.ts` doesn't enforce it either, and adding the
+    // check ONLY on the tool-call path would create asymmetric behaviour
+    // (a path that works through one channel and fails through the
+    // other). Sandbox enforcement is tracked as a separate follow-up
+    // covering both paths together.
+    const client = createBotHubClient(account);
+    const result = await client.sendFile({
+      channelId: to,
+      path: localPath,
+      caption: caption?.trim() || undefined,
+      attachmentType: attachmentHintFromExtension(extensionOf(localPath)),
+      parentId,
+    });
+    return jsonResult({
+      ok: true,
+      messageId: result.message_id,
+      channelId: result.channel_id,
+    });
+  },
+};

package/src/channel.test.ts

@@ -0,0 +1,150 @@
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+import type { ClawdbotConfig } from "openclaw/plugin-sdk/vama";
+import { describe, expect, it } from "vitest";
+import { vamaPlugin } from "./channel.js";
+
+function makeCfg(vama?: Record<string, unknown>): ClawdbotConfig {
+  return { channels: { vama } } as ClawdbotConfig;
+}
+
+describe("vamaPlugin", () => {
+  it("has correct meta", () => {
+    expect(vamaPlugin.id).toBe("vama");
+    expect(vamaPlugin.meta.label).toBe("Vama");
+  });
+
+  it("reports correct capabilities", () => {
+    expect(vamaPlugin.capabilities.chatTypes).toEqual(["direct"]);
+    expect(vamaPlugin.capabilities.threads).toBe(true);
+    // Media outbound: enabled in 2026.4.15-13 — `outbound.sendMedia` now uploads
+    // local workspace artefacts (e.g. `MEDIA:/home/app/.openclaw/...`)
+    // through BotHub's `/v1/bot/messages/file` endpoint instead of stripping
+    // them. See `outbound.ts` and `reply-dispatcher.ts` for the full path.
+    expect(vamaPlugin.capabilities.media).toBe(true);
+    expect(vamaPlugin.capabilities.reactions).toBe(false);
+    expect(vamaPlugin.capabilities.edit).toBe(false);
+    expect(vamaPlugin.capabilities.reply).toBe(true);
+  });
+
+  it("registers a message-actions adapter so the shared `message` tool is exposed", () => {
+    // Regression guard: dropping `actions:` from the plugin object collapses
+    // the structured outbound-file path back to MEDIA:-only, which is what
+    // caused bryan-talos to silently never attach files. Keep this assertion
+    // tight and minimal — the adapter's own behaviour is covered in
+    // `channel-actions.test.ts`.
+    expect(vamaPlugin.actions).toBeDefined();
+    expect(typeof vamaPlugin.actions?.describeMessageTool).toBe("function");
+    const discovery = vamaPlugin.actions!.describeMessageTool({
+      cfg: makeCfg({ enabled: true, botToken: "tok", bothubUrl: "https://b.example" }),
+      accountId: DEFAULT_ACCOUNT_ID,
+    });
+    expect(discovery?.actions).toContain("send");
+  });
+
+  describe("config.listAccountIds", () => {
+    it("returns default when no accounts configured", () => {
+      const ids = vamaPlugin.config.listAccountIds(makeCfg({ enabled: true }));
+      expect(ids).toEqual([DEFAULT_ACCOUNT_ID]);
+    });
+  });
+
+  describe("config.setAccountEnabled", () => {
+    it("sets enabled on default account", () => {
+      const cfg = makeCfg({ botToken: "tok" });
+      const next = vamaPlugin.config.setAccountEnabled!({
+        cfg,
+        accountId: DEFAULT_ACCOUNT_ID,
+        enabled: false,
+      });
+      expect((next.channels?.vama as Record<string, unknown>)?.enabled).toBe(false);
+    });
+
+    it("sets enabled on named account", () => {
+      const cfg = makeCfg({ accounts: { staging: { botToken: "tok" } } });
+      const next = vamaPlugin.config.setAccountEnabled!({
+        cfg,
+        accountId: "staging",
+        enabled: false,
+      });
+      const accounts = (next.channels?.vama as Record<string, unknown>)?.accounts as Record<
+        string,
+        Record<string, unknown>
+      >;
+      expect(accounts?.staging?.enabled).toBe(false);
+    });
+  });
+
+  describe("config.deleteAccount", () => {
+    it("removes vama config for default account", () => {
+      const cfg = makeCfg({ enabled: true, botToken: "tok" });
+      const next = vamaPlugin.config.deleteAccount!({ cfg, accountId: DEFAULT_ACCOUNT_ID });
+      expect((next.channels as Record<string, unknown>)?.vama).toBeUndefined();
+    });
+
+    it("removes named account from accounts map", () => {
+      const cfg = makeCfg({
+        enabled: true,
+        accounts: { staging: { botToken: "tok" }, prod: { botToken: "tok2" } },
+      });
+      const next = vamaPlugin.config.deleteAccount!({ cfg, accountId: "staging" });
+      const vama = next.channels?.vama as Record<string, unknown>;
+      const accounts = vama?.accounts as Record<string, unknown> | undefined;
+      expect(accounts?.staging).toBeUndefined();
+      expect(accounts?.prod).toBeDefined();
+    });
+  });
+
+  describe("config.isConfigured", () => {
+    it("returns true when configured", () => {
+      const cfg = makeCfg({ enabled: true, botToken: "tok", bothubUrl: "https://b.com" });
+      const account = vamaPlugin.config.resolveAccount(cfg, DEFAULT_ACCOUNT_ID);
+      expect(vamaPlugin.config.isConfigured!(account, cfg)).toBe(true);
+    });
+
+    it("returns false when not configured", () => {
+      const cfg = makeCfg({ enabled: true });
+      const account = vamaPlugin.config.resolveAccount(cfg, DEFAULT_ACCOUNT_ID);
+      expect(vamaPlugin.config.isConfigured!(account, cfg)).toBe(false);
+    });
+  });
+
+  describe("security.collectWarnings", () => {
+    it("warns when dmPolicy is open", () => {
+      const cfg = makeCfg({ enabled: true, botToken: "tok", bothubUrl: "https://b.com" });
+      const account = vamaPlugin.config.resolveAccount(cfg, DEFAULT_ACCOUNT_ID);
+      const warnings = vamaPlugin.security!.collectWarnings!({
+        cfg,
+        accountId: DEFAULT_ACCOUNT_ID,
+        account,
+      });
+      expect(warnings).toHaveLength(1);
+      expect((warnings as string[])[0]).toMatch(/dmPolicy="open"/);
+    });
+
+    it("does not warn when dmPolicy is pairing", () => {
+      const cfg = makeCfg({
+        enabled: true,
+        botToken: "tok",
+        bothubUrl: "https://b.com",
+        dmPolicy: "pairing",
+      });
+      const account = vamaPlugin.config.resolveAccount(cfg, DEFAULT_ACCOUNT_ID);
+      const warnings = vamaPlugin.security!.collectWarnings!({
+        cfg,
+        accountId: DEFAULT_ACCOUNT_ID,
+        account,
+      });
+      expect(warnings).toEqual([]);
+    });
+  });
+
+  describe("pairing", () => {
+    it("has idLabel set to vamaUserId", () => {
+      expect(vamaPlugin.pairing!.idLabel).toBe("vamaUserId");
+    });
+
+    it("normalizes allowlist entries", () => {
+      expect(vamaPlugin.pairing!.normalizeAllowEntry!("  user_123  ")).toBe("user_123");
+    });
+  });
+});

package/src/channel.ts

@@ -0,0 +1,256 @@
+import { resolveVamaAccount, listVamaAccountIds, resolveDefaultVamaAccountId } from "./accounts.js";
+import { vamaMessageActions } from "./channel-actions.js";
+import type { ChannelPlugin, ClawdbotConfig } from "./host-sdk.js";
+import {
+  buildBaseChannelStatusSummary,
+  createDefaultChannelRuntimeState,
+  DEFAULT_ACCOUNT_ID,
+  PAIRING_APPROVED_MESSAGE,
+} from "./host-sdk.js";
+import { monitorVamaProvider } from "./monitor.js";
+import { vamaOutbound } from "./outbound.js";
+import { probeVama } from "./probe.js";
+import { vamaSetupWizard } from "./setup-surface.js";
+import type { ResolvedVamaAccount, VamaConfig } from "./types.js";
+
+const meta = {
+  id: "vama",
+  label: "Vama",
+  selectionLabel: "Vama",
+  docsPath: "/channels/vama",
+  docsLabel: "vama",
+  blurb: "Vama chat integration via BotHub.",
+  order: 80,
+};
+
+export const vamaPlugin: ChannelPlugin<ResolvedVamaAccount> = {
+  id: "vama",
+  meta: { ...meta },
+  pairing: {
+    idLabel: "vamaUserId",
+    normalizeAllowEntry: (entry) => entry.trim(),
+    notifyApproval: async ({ cfg, id }) => {
+      // Send approval notification directly via BotHub user_id targeting.
+      const account = resolveVamaAccount({ cfg });
+      if (!account.configured) {
+        return;
+      }
+      try {
+        const { createBotHubClient } = await import("./client.js");
+        const client = createBotHubClient(account);
+        await client.sendMessage({ userId: id, text: PAIRING_APPROVED_MESSAGE });
+      } catch {
+        // Best-effort — user will see the effect when they next message the bot.
+      }
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct"],
+    polls: false,
+    threads: true,
+    media: true,
+    reactions: false,
+    edit: false,
+    reply: true,
+  },
+  reload: { configPrefixes: ["channels.vama"] },
+  configSchema: {
+    schema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        enabled: { type: "boolean" },
+        botToken: { type: "string" },
+        webhookSecret: { type: "string" },
+        webhookSecretFile: { type: "string" },
+        bothubUrl: { type: "string" },
+        webhookPath: { type: "string" },
+        webhookPort: { type: "integer", minimum: 1 },
+        webhookHost: { type: "string" },
+        webhookUrl: { type: "string" },
+        transport: { type: "string", enum: ["auto", "webhook", "websocket"] },
+        dmPolicy: { type: "string", enum: ["open", "pairing", "allowlist"] },
+        allowFrom: { type: "array", items: { oneOf: [{ type: "string" }, { type: "number" }] } },
+        textChunkLimit: { type: "integer", minimum: 1 },
+        accounts: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            properties: {
+              enabled: { type: "boolean" },
+              name: { type: "string" },
+              botToken: { type: "string" },
+              webhookSecret: { type: "string" },
+              webhookSecretFile: { type: "string" },
+              bothubUrl: { type: "string" },
+              webhookPath: { type: "string" },
+              webhookPort: { type: "integer", minimum: 1 },
+              webhookHost: { type: "string" },
+              webhookUrl: { type: "string" },
+              transport: { type: "string", enum: ["auto", "webhook", "websocket"] },
+            },
+          },
+        },
+      },
+    },
+  },
+  config: {
+    listAccountIds: (cfg) => listVamaAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveVamaAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultVamaAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) => {
+      const isDefault = accountId === DEFAULT_ACCOUNT_ID;
+      if (isDefault) {
+        return {
+          ...cfg,
+          channels: {
+            ...cfg.channels,
+            vama: { ...cfg.channels?.vama, enabled },
+          },
+        };
+      }
+      const vamaCfg = cfg.channels?.vama as VamaConfig | undefined;
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          vama: {
+            ...vamaCfg,
+            accounts: {
+              ...vamaCfg?.accounts,
+              [accountId]: { ...vamaCfg?.accounts?.[accountId], enabled },
+            },
+          },
+        },
+      };
+    },
+    deleteAccount: ({ cfg, accountId }) => {
+      const isDefault = accountId === DEFAULT_ACCOUNT_ID;
+      if (isDefault) {
+        const next = { ...cfg } as ClawdbotConfig;
+        const nextChannels = { ...cfg.channels };
+        delete (nextChannels as Record<string, unknown>).vama;
+        if (Object.keys(nextChannels).length > 0) {
+          next.channels = nextChannels;
+        } else {
+          delete next.channels;
+        }
+        return next;
+      }
+      const vamaCfg = cfg.channels?.vama as VamaConfig | undefined;
+      const accounts = { ...vamaCfg?.accounts };
+      delete accounts[accountId];
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          vama: {
+            ...vamaCfg,
+            accounts: Object.keys(accounts).length > 0 ? accounts : undefined,
+          },
+        },
+      };
+    },
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+      name: account.name,
+      bothubUrl: account.bothubUrl,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) => {
+      const account = resolveVamaAccount({ cfg, accountId });
+      return (account.config?.allowFrom ?? []).map((entry) => String(entry));
+    },
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom.map((entry) => String(entry).trim()).filter(Boolean),
+  },
+  security: {
+    collectWarnings: ({ cfg, accountId }) => {
+      const account = resolveVamaAccount({ cfg, accountId });
+      const dmPolicy = account.config?.dmPolicy ?? "open";
+      if (dmPolicy !== "open") {
+        return [];
+      }
+      return [
+        `- Vama[${account.accountId}]: dmPolicy="open" allows any user to DM the bot. Set channels.vama.dmPolicy="allowlist" + channels.vama.allowFrom to restrict senders.`,
+      ];
+    },
+  },
+  setup: {
+    resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+    applyAccountConfig: ({ cfg, accountId }) => {
+      const isDefault = !accountId || accountId === DEFAULT_ACCOUNT_ID;
+      if (isDefault) {
+        return {
+          ...cfg,
+          channels: {
+            ...cfg.channels,
+            vama: { ...cfg.channels?.vama, enabled: true },
+          },
+        };
+      }
+      const vamaCfg = cfg.channels?.vama as VamaConfig | undefined;
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          vama: {
+            ...vamaCfg,
+            accounts: {
+              ...vamaCfg?.accounts,
+              [accountId]: { ...vamaCfg?.accounts?.[accountId], enabled: true },
+            },
+          },
+        },
+      };
+    },
+  },
+  setupWizard: vamaSetupWizard,
+  outbound: vamaOutbound,
+  actions: vamaMessageActions,
+  status: {
+    defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID, { port: null }),
+    buildChannelSummary: ({ snapshot }) => ({
+      ...buildBaseChannelStatusSummary(snapshot),
+      port: snapshot.port ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account }) => await probeVama(account),
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+      name: account.name,
+      bothubUrl: account.bothubUrl,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      port: runtime?.port ?? null,
+      probe,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      // NOTE: import statically (not via `await import("./monitor.js")`).
+      // A dynamic import here is resolved at runtime by Node's native ESM
+      // loader, which bypasses Jiti and produces a *separate* instance of
+      // ./runtime.js (transitively imported by monitor->bot). The channel
+      // entry's setVamaRuntime() then writes to a different module instance
+      // than the one bot.ts reads from, causing "Vama runtime not initialized".
+      const account = resolveVamaAccount({ cfg: ctx.cfg, accountId: ctx.accountId });
+      const port = account.config?.webhookPort ?? null;
+      ctx.setStatus({ accountId: ctx.accountId, port });
+      ctx.log?.info(`starting vama[${ctx.accountId}]`);
+      return monitorVamaProvider({
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        accountId: ctx.accountId,
+      });
+    },
+  },
+};

package/src/cli-metadata.ts

@@ -0,0 +1,19 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/channel-plugin-common";
+
+export function registerVamaCliMetadata(api: OpenClawPluginApi) {
+  api.registerCli(
+    async ({ program }) => {
+      const { registerVamaCli } = await import("./cli.js");
+      registerVamaCli({ program });
+    },
+    {
+      descriptors: [
+        {
+          name: "vama",
+          description: "Connect this OpenClaw to Vama and manage the Vama channel",
+          hasSubcommands: true,
+        },
+      ],
+    },
+  );
+}