@andreprado/agentkit 0.1.0-alpha.10

package/src/cli/commands/channels.ts

@@ -0,0 +1,810 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import type { ParsedArgs } from "../args";
+import { cloudFetch, cloudGet, cloudPost, readCloudError } from "../cloud-client";
+import { parseCloudApiUrl } from "../flags";
+import { loadAgentCapsule } from "../../runtime/config";
+import { readLocalDeployStateIfExists, type LocalDeployState } from "../../runtime/core/deploy-state";
+import { loadCapsuleEnv } from "../../runtime/env";
+import type { AgentChannel } from "../../index";
+
+type DeployState = LocalDeployState;
+
+type CloudChannel = {
+  id: string;
+  name: string;
+  type: "website" | "telegram" | "whatsapp";
+  provider: "agentkit" | "telegram" | "zapster" | "meta";
+  status: string;
+  webhook_url: string;
+  required_secrets: Array<{ name: string; status: string }>;
+  buffer?: AgentChannel["buffer"];
+};
+
+type CloudDelivery = {
+  id: string;
+  channel_id: string;
+  direction: string;
+  status: string;
+  provider: {
+    event_id?: string;
+  };
+  received_at: string;
+  updated_at?: string;
+  error?: {
+    code: string;
+    message: string;
+  };
+  events?: Array<{
+    state: string;
+    message: string;
+    created_at: string;
+  }>;
+};
+
+type ChannelSetupResponse = {
+  channel: CloudChannel;
+  setup?: {
+    provider: "telegram";
+    webhook_url: string;
+    status: "configured";
+    bot_username?: string;
+    get_webhook_info?: {
+      url: string;
+      pending_update_count: number;
+    };
+  };
+};
+
+type ChannelDoctorReport = {
+  channel: CloudChannel;
+  checks: Array<{
+    name: string;
+    status: "ok" | "warn" | "fail" | "unknown";
+    message: string;
+    fix?: string;
+  }>;
+  last_delivery: {
+    inbound: CloudDelivery | null;
+    outbound: CloudDelivery | null;
+  };
+  probable_error: string | null;
+  suggested_fix: string | null;
+};
+
+export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
+  await loadLocalEnvIntoProcess(process.cwd());
+
+  const [subcommand, first, second] = args.positional;
+
+  if (subcommand === "list") {
+    const deployState = await readDeployStateIfExists(process.cwd());
+
+    if (deployState) {
+      const channels = await cloudGet<{ channels: CloudChannel[] }>(
+        parseCloudApiUrl(args.flags.api),
+        `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
+      );
+      printChannelsTable(channels.channels);
+      return;
+    }
+
+    const capsule = await loadAgentCapsule(process.cwd());
+    printChannelsTable(
+      (capsule.config.channels ?? []).map((channel) => ({
+        id: "",
+        name: channel.name,
+        type: channel.type,
+        provider: channel.provider,
+        status: "local_config",
+        webhook_url: "",
+        required_secrets: channel.secrets.map((name) => ({ name, status: "missing" })),
+      })),
+    );
+    return;
+  }
+
+  if (subcommand === "add") {
+    const type = first;
+    const name = second;
+
+    if (!type || !name || (type !== "website" && type !== "telegram" && type !== "whatsapp")) {
+      throw new Error("Usage: agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta]");
+    }
+
+    const response = await createHostedChannel(type, name, args.flags.provider, args.flags.api);
+    printChannelStatus(response.channel);
+    printSecretRepairHint(response.channel);
+    return;
+  }
+
+  if (subcommand === "connect") {
+    const type = first;
+    const name = second;
+
+    if (!type || !name || (type !== "website" && type !== "telegram" && type !== "whatsapp")) {
+      throw new Error("Usage: agentkit channels connect <website|telegram|whatsapp> <name> [--provider zapster|meta]");
+    }
+
+    const created = await createHostedChannel(type, name, args.flags.provider, args.flags.api);
+    let channel = created.channel;
+    printChannelStatus(channel);
+    printSecretRepairHint(channel);
+
+    if (hasMissingRequiredSecrets(channel)) {
+      console.log("");
+      console.log("Connect blocked: set the missing managed secrets, then rerun this same command.");
+      console.log("Run: npm run agentkit -- secret sync --from-local");
+      process.exitCode = 1;
+      return;
+    }
+
+    if (channel.type === "telegram") {
+      const setup = await applyTelegramWebhook(channel, args.flags.api);
+      channel = setup.channel ?? channel;
+      console.log("Telegram webhook confirmed.");
+      if (setup.setup?.get_webhook_info) {
+        console.log(`Telegram pending updates: ${setup.setup.get_webhook_info.pending_update_count}`);
+      }
+
+      const smoke = await runChannelSmoke(channel, args.flags.api, args.flags.message);
+      console.log(`Smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+      printTelegramHumanNextStep(channel.name, setup.setup?.bot_username);
+      return;
+    }
+
+    if (channel.type === "whatsapp") {
+      console.log("Smoke: skipped until the provider webhook is configured.");
+      console.log(`Next human step: paste ${channel.webhook_url} into ${channel.provider}'s webhook settings.`);
+    } else {
+      const smoke = await runChannelSmoke(channel, args.flags.api, args.flags.message);
+      console.log(`Smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+      console.log(`Next human step: use ${channel.webhook_url} from your website client.`);
+    }
+    return;
+  }
+
+  if (subcommand === "setup") {
+    if (!first) {
+      throw new Error("Usage: agentkit channels setup <name> [--apply]");
+    }
+
+    const channel = await resolveCloudChannelByName(first, args.flags.api);
+    printChannelStatus(channel);
+    if (channel.type === "telegram") {
+      if (args.flags.apply) {
+        const setup = await applyTelegramWebhook(channel, args.flags.api);
+        console.log("Telegram webhook confirmed.");
+        printChannelStatus(setup.channel ?? channel);
+        printTelegramHumanNextStep(channel.name, setup.setup?.bot_username);
+      } else {
+        console.log(`Setup: call Telegram setWebhook with ${channel.webhook_url}`);
+        console.log("Use --apply to mutate Telegram webhook settings.");
+      }
+    } else if (channel.type === "whatsapp") {
+      console.log(`Next step: paste this URL into ${channel.provider}'s webhook settings.`);
+    } else {
+      console.log(`Website endpoint: ${channel.webhook_url}`);
+      console.log("Use this endpoint from the AgentKit website client or a signed server-to-server test.");
+    }
+    return;
+  }
+
+  if (subcommand === "status") {
+    if (!first) {
+      throw new Error("Usage: agentkit channels status <name>");
+    }
+
+    const channel = await resolveCloudChannelByName(first, args.flags.api);
+    printChannelStatus(channel);
+    await printChannelDeliverySummary(channel, args.flags.api);
+    return;
+  }
+
+  if (subcommand === "doctor") {
+    if (!first) {
+      throw new Error("Usage: agentkit channels doctor <name>");
+    }
+
+    const channel = await resolveCloudChannelByName(first, args.flags.api);
+    const report = await cloudGet<{ doctor: ChannelDoctorReport }>(
+      parseCloudApiUrl(args.flags.api),
+      `/v1/channels/${encodeURIComponent(channel.id)}/doctor`,
+    );
+    printChannelDoctor(report.doctor);
+
+    if (report.doctor.checks.some((check) => check.status === "fail")) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (subcommand === "test") {
+    if (!first) {
+      throw new Error('Usage: agentkit channels test <name> [--message "hello"] [--fixture <path>]');
+    }
+
+    const channel = await resolveCloudChannelByName(first, args.flags.api);
+    const apiUrl = parseCloudApiUrl(args.flags.api);
+    const body = await channelTestBody(channel, args.flags.message, args.flags.fixture);
+    const signed = await runServerSignedChannelTest(channel, apiUrl, body);
+    const response = signed.response;
+    const payload = signed.payload;
+
+    console.log(JSON.stringify(payload, null, 2));
+    if (!response.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (subcommand === "deliveries") {
+    if (first === "list") {
+      if (!second) {
+        throw new Error("Usage: agentkit channels deliveries list <name>");
+      }
+
+      const channel = await resolveCloudChannelByName(second, args.flags.api);
+      const response = await cloudGet<{ deliveries: CloudDelivery[] }>(
+        parseCloudApiUrl(args.flags.api),
+        `/v1/channels/${encodeURIComponent(channel.id)}/deliveries`,
+      );
+
+      if (response.deliveries.length === 0) {
+        console.log("No channel deliveries found.");
+        return;
+      }
+
+      console.log("ID\tCHANNEL\tDIRECTION\tSTATUS\tPROVIDER_EVENT\tRECEIVED");
+      for (const delivery of response.deliveries) {
+        console.log(
+          [
+            delivery.id,
+            delivery.channel_id,
+            delivery.direction,
+            delivery.status,
+            delivery.provider.event_id ?? "",
+            delivery.received_at,
+          ].join("\t"),
+        );
+      }
+      return;
+    }
+
+    if (first === "show") {
+      if (!second) {
+        throw new Error("Usage: agentkit channels deliveries show <delivery-id>");
+      }
+
+      const response = await cloudGet<{ delivery: CloudDelivery }>(
+        parseCloudApiUrl(args.flags.api),
+        `/v1/channel-deliveries/${encodeURIComponent(second)}`,
+      );
+      console.log(JSON.stringify(response.delivery, null, 2));
+      return;
+    }
+  }
+
+  throw new Error(
+    "Usage: agentkit channels list | add | connect | setup | status | doctor | test | deliveries list | deliveries show",
+  );
+}
+
+async function createHostedChannel(
+  type: "website" | "telegram" | "whatsapp",
+  name: string,
+  providerFlag: string | boolean | undefined,
+  apiFlag: string | boolean | undefined,
+): Promise<{ channel: CloudChannel }> {
+  const deployState = await readDeployStateRequired(process.cwd());
+  const provider = channelProviderForCli(type, providerFlag);
+  const localChannel = await readLocalChannelConfig(process.cwd(), type, provider, name);
+  const payload = {
+    name,
+    type,
+    provider,
+    secrets: localChannel?.secrets ?? defaultChannelSecretsForCli(type, provider),
+    ...(localChannel?.limits ? { limits: channelLimitsForApi(localChannel.limits) } : {}),
+    ...(localChannel?.buffer ? { buffer: localChannel.buffer } : {}),
+  };
+
+  return cloudPost<{ channel: CloudChannel }>(
+    parseCloudApiUrl(apiFlag),
+    `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
+    payload,
+  );
+}
+
+async function runChannelSmoke(
+  channel: CloudChannel,
+  apiFlag: string | boolean | undefined,
+  messageFlag: string | boolean | undefined,
+): Promise<{ status: string; delivery_id?: string }> {
+  const body = await channelTestBody(channel, messageFlag, undefined);
+  const { response, payload } = await runServerSignedChannelTest(channel, parseCloudApiUrl(apiFlag), body);
+
+  if (!response.ok) {
+    throw new Error(readCloudError(payload, response.status));
+  }
+
+  if (isRecord(payload) && typeof payload.status === "string") {
+    return {
+      status: payload.status,
+      ...(typeof payload.delivery_id === "string" ? { delivery_id: payload.delivery_id } : {}),
+    };
+  }
+
+  return { status: "unknown" };
+}
+
+async function runServerSignedChannelTest(
+  channel: CloudChannel,
+  apiUrl: string,
+  rawBody: string,
+): Promise<{ response: Response; payload: unknown }> {
+  const response = await cloudFetch(apiUrl, `/v1/channels/${encodeURIComponent(channel.id)}/test`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ raw_body: rawBody }),
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok && isUnsupportedChannelTestRoute(payload)) {
+    return runLocallySignedChannelTest(channel, apiUrl, rawBody);
+  }
+
+  return { response, payload };
+}
+
+async function runLocallySignedChannelTest(
+  channel: CloudChannel,
+  apiUrl: string,
+  rawBody: string,
+): Promise<{ response: Response; payload: unknown }> {
+  const webhookUrl = new URL(channel.webhook_url);
+
+  if (channel.required_secrets.some((secret) => secret.name === "ZAPSTER_WEBHOOK_TOKEN")) {
+    webhookUrl.searchParams.set("token", process.env.ZAPSTER_WEBHOOK_TOKEN ?? "");
+  }
+
+  const path = `${webhookUrl.pathname}${webhookUrl.search}`;
+  const headers = channelTestHeaders(channel);
+  const response = await cloudFetch(apiUrl, path, {
+    method: "POST",
+    headers,
+    body: rawBody,
+  });
+  const payload = await response.json().catch(() => null);
+
+  return { response, payload };
+}
+
+function isUnsupportedChannelTestRoute(payload: unknown): boolean {
+  return (
+    isRecord(payload) &&
+    isRecord(payload.error) &&
+    (payload.error.code === "not_found" ||
+      payload.error.code === "channel_store_not_configured" ||
+      payload.error.code === "channel_delivery_not_found")
+  );
+}
+
+async function applyTelegramWebhook(
+  channel: CloudChannel,
+  apiFlag: string | boolean | undefined,
+): Promise<ChannelSetupResponse> {
+  try {
+    return await cloudPost<ChannelSetupResponse>(
+      parseCloudApiUrl(apiFlag),
+      `/v1/channels/${encodeURIComponent(channel.id)}/setup`,
+      {},
+    );
+  } catch (error) {
+    if (!shouldFallbackToLocalTelegramSetup(error)) {
+      throw error;
+    }
+  }
+
+  const botToken = process.env.TELEGRAM_BOT_TOKEN;
+  const secretToken = process.env.TELEGRAM_WEBHOOK_SECRET;
+
+  if (!botToken || !secretToken) {
+    throw new Error("TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET must be set to apply Telegram setup.");
+  }
+
+  let response: Response;
+  const apiBaseUrl = telegramApiBaseUrlFromEnv();
+
+  try {
+    response = await fetch(new URL(`/bot${botToken}/setWebhook`, apiBaseUrl).href, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        url: channel.webhook_url,
+        secret_token: secretToken,
+        allowed_updates: ["message"],
+      }),
+    });
+  } catch {
+    throw new Error("Telegram setWebhook request failed before Telegram returned a response.");
+  }
+
+  const payload = await response.json().catch(() => ({}));
+
+  if (!response.ok || !isTelegramOk(payload)) {
+    throw new Error(readTelegramSetupError(payload, response.status));
+  }
+
+  const webhookInfo = await fetch(new URL(`/bot${botToken}/getWebhookInfo`, apiBaseUrl).href)
+    .then((telegramResponse) => telegramResponse.json())
+    .catch(() => null);
+  const webhookUrl =
+    webhookInfo &&
+    typeof webhookInfo === "object" &&
+    "result" in webhookInfo &&
+    webhookInfo.result &&
+    typeof webhookInfo.result === "object" &&
+    "url" in webhookInfo.result &&
+    typeof webhookInfo.result.url === "string"
+      ? webhookInfo.result.url
+      : "";
+
+  if (webhookUrl !== channel.webhook_url) {
+    throw new Error(`Telegram getWebhookInfo returned ${webhookUrl || "no webhook URL"} instead of ${channel.webhook_url}.`);
+  }
+
+  return {
+    channel: {
+      ...channel,
+      status: "connected",
+    },
+    setup: {
+      provider: "telegram",
+      webhook_url: channel.webhook_url,
+      status: "configured",
+      get_webhook_info: {
+        url: webhookUrl,
+        pending_update_count: 0,
+      },
+    },
+  };
+}
+
+function shouldFallbackToLocalTelegramSetup(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return /Unknown AgentKit Cloud route|does not support channel delivery records yet|does not support channel resources yet/.test(
+    error.message,
+  );
+}
+
+function isTelegramOk(payload: unknown): payload is { ok: true } {
+  return Boolean(payload && typeof payload === "object" && "ok" in payload && payload.ok === true);
+}
+
+function readTelegramSetupError(payload: unknown, status: number): string {
+  if (payload && typeof payload === "object" && "description" in payload && typeof payload.description === "string") {
+    return `Telegram setWebhook failed: ${payload.description}`;
+  }
+
+  return `Telegram setWebhook failed with HTTP ${status}.`;
+}
+
+function telegramApiBaseUrlFromEnv(): string {
+  return process.env.AGENTKIT_TELEGRAM_API_BASE_URL ?? "https://api.telegram.org";
+}
+
+async function loadLocalEnvIntoProcess(cwd: string): Promise<void> {
+  const env = await loadCapsuleEnv(cwd, process.env);
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined && process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}
+
+function printTelegramHumanNextStep(channelName: string, botUsername: string | undefined): void {
+  console.log("");
+  console.log("Next human step:");
+  console.log(`  Open ${botUsername ? `@${botUsername}` : "your Telegram bot"} in Telegram`);
+  console.log("  Send /start");
+  console.log('  Send "hello"');
+  console.log(`  Then run: npm run agentkit -- channels deliveries list ${channelName}`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+async function readDeployStateIfExists(cwd: string): Promise<DeployState | null> {
+  return readLocalDeployStateIfExists(cwd);
+}
+
+async function readDeployStateRequired(cwd: string): Promise<DeployState> {
+  const state = await readDeployStateIfExists(cwd);
+
+  if (!state?.deploy_id) {
+    throw new Error("No .agentkit/deploy.json found. Run agentkit deploy before creating hosted channels.");
+  }
+
+  return state;
+}
+
+function printChannelsTable(channels: CloudChannel[]): void {
+  if (channels.length === 0) {
+    console.log("No channels found.");
+    return;
+  }
+
+  console.log("NAME\tTYPE\tPROVIDER\tSTATUS\tLAST_EVENT");
+  for (const channel of channels) {
+    console.log([channel.name, channel.type, channel.provider, channel.status, ""].join("\t"));
+  }
+}
+
+function printChannelStatus(channel: CloudChannel): void {
+  console.log(`Channel: ${channel.name}`);
+  if (channel.id) {
+    console.log(`ID: ${channel.id}`);
+  }
+  console.log(`Type: ${channel.type}`);
+  console.log(`Provider: ${channel.provider}`);
+  console.log(`Status: ${channel.status}`);
+  if (channel.webhook_url) {
+    console.log(`Webhook URL: ${channel.webhook_url}`);
+  }
+  console.log("Required secrets:");
+  if (channel.required_secrets.length === 0 && defaultChannelSecretsForCli(channel.type, channel.provider).length > 0) {
+    console.log(
+      `  control-plane channel metadata bug: required_secrets is empty for ${channel.type}/${channel.provider}`,
+    );
+  } else {
+    for (const secret of channel.required_secrets) {
+      console.log(`  ${secret.name}: ${secret.status}`);
+    }
+  }
+  if (channel.buffer) {
+    if (channel.buffer.mode === "off") {
+      console.log("Buffer: off");
+    } else {
+      console.log(
+        `Buffer: debounce quiet=${channel.buffer.quietWindowMs}ms max_wait=${channel.buffer.maxWaitMs}ms max_messages=${channel.buffer.maxMessages} max_chars=${channel.buffer.maxChars}`,
+      );
+    }
+  }
+}
+
+function printSecretRepairHint(channel: CloudChannel): void {
+  if (channel.required_secrets.length > 0 || defaultChannelSecretsForCli(channel.type, channel.provider).length === 0) {
+    return;
+  }
+
+  console.log(
+    "Hint: control-plane channel metadata bug. Rerun add/connect against the updated control-plane to repair required_secrets.",
+  );
+}
+
+function hasMissingRequiredSecrets(channel: CloudChannel): boolean {
+  const expected = defaultChannelSecretsForCli(channel.type, channel.provider);
+
+  if (channel.required_secrets.length === 0 && expected.length > 0) {
+    return true;
+  }
+
+  return channel.required_secrets.some((secret) => secret.status !== "set");
+}
+
+async function printChannelDeliverySummary(
+  channel: CloudChannel,
+  apiFlag: string | boolean | undefined,
+): Promise<void> {
+  const response = await cloudGet<{ deliveries: CloudDelivery[] }>(
+    parseCloudApiUrl(apiFlag),
+    `/v1/channels/${encodeURIComponent(channel.id)}/deliveries`,
+  );
+  const inbound = [...response.deliveries].reverse().find((delivery) => delivery.direction === "inbound");
+  const outbound = [...response.deliveries].reverse().find((delivery) => delivery.direction === "outbound");
+
+  console.log("Recent delivery:");
+  console.log(`  Last inbound: ${inbound ? `${inbound.status} ${inbound.received_at}` : "none"}`);
+  console.log(`  Last outbound: ${outbound ? `${outbound.status} ${outbound.received_at}` : "none"}`);
+  console.log("Provider health: not_checked");
+}
+
+function printChannelDoctor(report: ChannelDoctorReport): void {
+  console.log(`Channel doctor: ${report.channel.name}`);
+  console.log("");
+  console.log("Checks:");
+  for (const check of report.checks) {
+    console.log(`  ${formatCheckStatus(check.status)} ${check.name}: ${check.message}`);
+    if (check.fix) {
+      console.log(`    Fix: ${check.fix}`);
+    }
+  }
+
+  console.log("");
+  console.log("Last delivery:");
+  console.log(
+    `  Inbound: ${report.last_delivery.inbound ? `${report.last_delivery.inbound.status} ${report.last_delivery.inbound.updated_at ?? report.last_delivery.inbound.received_at}` : "none"}`,
+  );
+  console.log(
+    `  Outbound: ${report.last_delivery.outbound ? `${report.last_delivery.outbound.status} ${report.last_delivery.outbound.updated_at ?? report.last_delivery.outbound.received_at}` : "none"}`,
+  );
+
+  if (report.probable_error) {
+    console.log("");
+    console.log(`Probable error: ${report.probable_error}`);
+  }
+  if (report.suggested_fix) {
+    console.log(`Suggested fix: ${report.suggested_fix}`);
+  }
+}
+
+function formatCheckStatus(status: ChannelDoctorReport["checks"][number]["status"]): string {
+  if (status === "ok") {
+    return "OK";
+  }
+
+  if (status === "warn") {
+    return "WARN";
+  }
+
+  if (status === "fail") {
+    return "FAIL";
+  }
+
+  return "UNKNOWN";
+}
+
+async function resolveCloudChannelByName(name: string, apiFlag: string | boolean | undefined): Promise<CloudChannel> {
+  const deployState = await readDeployStateRequired(process.cwd());
+  const response = await cloudGet<{ channels: CloudChannel[] }>(
+    parseCloudApiUrl(apiFlag),
+    `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
+  );
+  const channel = response.channels.find((candidate) => candidate.name === name);
+
+  if (!channel) {
+    throw new Error(`Channel "${name}" was not found for deploy ${deployState.deploy_id}.`);
+  }
+
+  return channel;
+}
+
+function channelProviderForCli(type: string, providerFlag: string | boolean | undefined): string {
+  if (type === "website") {
+    return "agentkit";
+  }
+
+  if (type === "telegram") {
+    return "telegram";
+  }
+
+  const provider = providerFlag ?? "zapster";
+
+  if (provider !== "zapster" && provider !== "meta") {
+    throw new Error('WhatsApp provider must be "zapster" or "meta".');
+  }
+
+  return provider;
+}
+
+function defaultChannelSecretsForCli(type: string, provider: string): string[] {
+  if (type === "website") {
+    return ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"];
+  }
+
+  if (type === "telegram") {
+    return ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"];
+  }
+
+  if (type === "whatsapp" && provider === "zapster") {
+    return ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"];
+  }
+
+  if (type === "whatsapp" && provider === "meta") {
+    return ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"];
+  }
+
+  return [];
+}
+
+async function readLocalChannelConfig(
+  cwd: string,
+  type: string,
+  provider: string,
+  name: string,
+): Promise<AgentChannel | null> {
+  const capsule = await loadAgentCapsule(cwd);
+  return (
+    (capsule.config.channels ?? []).find(
+      (channel) => channel.name === name && channel.type === type && channel.provider === provider,
+    ) ?? null
+  );
+}
+
+function channelLimitsForApi(limits: NonNullable<AgentChannel["limits"]>): {
+  messages_per_day?: number;
+  usd_per_day?: number;
+} {
+  return {
+    ...(limits.messagesPerDay ? { messages_per_day: limits.messagesPerDay } : {}),
+    ...(limits.usdPerDay ? { usd_per_day: limits.usdPerDay } : {}),
+  };
+}
+
+async function channelTestBody(
+  channel: CloudChannel,
+  messageFlag: string | boolean | undefined,
+  fixtureFlag: string | boolean | undefined,
+): Promise<string> {
+  if (typeof fixtureFlag === "string") {
+    return readFile(resolve(process.cwd(), fixtureFlag), "utf8");
+  }
+
+  const message = typeof messageFlag === "string" ? messageFlag : "hello";
+
+  if (channel.type === "telegram") {
+    return JSON.stringify({
+      update_id: Date.now(),
+      message: {
+        message_id: 1,
+        chat: { id: 456, type: "private" },
+        from: { id: 123, first_name: "AgentKit" },
+        text: message,
+      },
+    });
+  }
+
+  if (channel.type === "whatsapp") {
+    return JSON.stringify({
+      event_id: `evt_${Date.now()}`,
+      instance_id: "local",
+      message: {
+        id: `msg_${Date.now()}`,
+        from: "5511999999999",
+        type: "text",
+        text: { body: message },
+      },
+    });
+  }
+
+  return JSON.stringify({
+    event_id: `web_${Date.now()}`,
+    visitor_id: "visitor_test",
+    message: {
+      id: `msg_${Date.now()}`,
+      text: message,
+    },
+  });
+}
+
+function channelTestHeaders(channel: CloudChannel): Headers {
+  const headers = new Headers({ "Content-Type": "application/json" });
+
+  if (channel.type === "website") {
+    const token = process.env.AGENTKIT_WEBSITE_CHANNEL_TOKEN;
+
+    if (token) {
+      headers.set("Authorization", `Bearer ${token}`);
+    }
+  }
+
+  if (channel.type === "telegram") {
+    headers.set("X-Telegram-Bot-Api-Secret-Token", process.env.TELEGRAM_WEBHOOK_SECRET ?? "");
+  }
+
+  if (channel.type === "whatsapp" && channel.provider === "zapster") {
+    headers.set("X-Instance-ID", process.env.ZAPSTER_INSTANCE_ID ?? "");
+    headers.set("X-Webhook-ID", process.env.ZAPSTER_WEBHOOK_ID ?? "");
+    headers.set("X-Message-ID", `cli_msg_${Date.now()}`);
+    headers.set("X-Attempt-Count", "1");
+    headers.set("User-Agent", "Zapsterapi/agentkit-cli");
+  }
+
+  return headers;
+}