@andreprado/agentkit 0.1.0-alpha.9 → 0.1.0

package/src/cli/commands/channels.ts

@@ -1,3 +1,4 @@
+import { createHmac } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
@@ -14,12 +15,18 @@ type DeployState = LocalDeployState;
 type CloudChannel = {
   id: string;
   name: string;
-  type: "website" | "telegram" | "whatsapp";
-  provider: "agentkit" | "telegram" | "zapster" | "meta";
+  type: "website" | "telegram" | "whatsapp" | "discord" | "slack" | "webhook";
+  provider: "agentkit" | "telegram" | "zapster" | "meta" | "uazapi" | "evolution" | "discord" | "slack" | "generic";
+  mode?: "interactions" | "bot";
+  direction?: "inbound" | "outbound";
   status: string;
   webhook_url: string;
   required_secrets: Array<{ name: string; status: string }>;
   buffer?: AgentChannel["buffer"];
+  audio?: AgentChannel["audio"];
+  reply_to?: Extract<AgentChannel, { replyTo?: unknown }>["replyTo"];
+  url_secret?: string;
+  auth?: Extract<AgentChannel, { type: "webhook"; direction: "outbound" }>["auth"];
 };
 
 type CloudDelivery = {
@@ -43,13 +50,44 @@ type CloudDelivery = {
   }>;
 };
 
+type CloudChannelBuffer = {
+  channel_id: string;
+  deploy_id: string;
+  conversation_id: string;
+  job_id?: string;
+  delivery_id?: string;
+  buffered_delivery_ids: string[];
+  buffered_message_count: number;
+  buffered_char_count: number;
+  status: string;
+  first_received_at: string;
+  last_received_at: string;
+  available_at?: string;
+  age_ms: number;
+  stale: boolean;
+  message_preview: string;
+};
+
+type ChannelBufferActionResponse = {
+  buffer: CloudChannelBuffer | null;
+  job: {
+    id: string;
+    status: string;
+    conversation_id: string;
+  } | null;
+  cleared?: boolean;
+  retried?: boolean;
+};
+
 type ChannelSetupResponse = {
   channel: CloudChannel;
   setup?: {
-    provider: "telegram";
+    provider: "telegram" | "uazapi" | "evolution";
     webhook_url: string;
     status: "configured";
     bot_username?: string;
+    webhook_count?: number;
+    matched_webhook_id?: string;
     get_webhook_info?: {
       url: string;
       pending_update_count: number;
@@ -65,6 +103,7 @@ type ChannelDoctorReport = {
     message: string;
     fix?: string;
   }>;
+  buffers: CloudChannelBuffer[];
   last_delivery: {
     inbound: CloudDelivery | null;
     outbound: CloudDelivery | null;
@@ -76,7 +115,7 @@ type ChannelDoctorReport = {
 export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
   await loadLocalEnvIntoProcess(process.cwd());
 
-  const [subcommand, first, second] = args.positional;
+  const [subcommand, first, second, third] = args.positional;
 
   if (subcommand === "list") {
     const deployState = await readDeployStateIfExists(process.cwd());
@@ -97,6 +136,7 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
         name: channel.name,
         type: channel.type,
         provider: channel.provider,
+        ...(channel.type === "discord" ? { mode: channel.mode } : {}),
         status: "local_config",
         webhook_url: "",
         required_secrets: channel.secrets.map((name) => ({ name, status: "missing" })),
@@ -109,11 +149,11 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     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]");
+    if (!type || !name || !isCliChannelType(type)) {
+      throw new Error("Usage: agentkit channels add <website|telegram|whatsapp|discord|slack|webhook> <name> [--provider zapster|meta|uazapi|evolution] [--mode interactions|bot]");
     }
 
-    const response = await createHostedChannel(type, name, args.flags.provider, args.flags.api);
+    const response = await createHostedChannel(type, name, args.flags.provider, args.flags.mode, args.flags.api);
     printChannelStatus(response.channel);
     printSecretRepairHint(response.channel);
     return;
@@ -123,16 +163,18 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     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]");
+    if (!type || !name || !isCliChannelType(type)) {
+      throw new Error("Usage: agentkit channels connect <website|telegram|whatsapp|discord|slack|webhook> <name> [--provider zapster|meta|uazapi|evolution] [--mode interactions|bot]");
     }
 
-    const created = await createHostedChannel(type, name, args.flags.provider, args.flags.api);
+    const created = await createHostedChannel(type, name, args.flags.provider, args.flags.mode, args.flags.api);
     let channel = created.channel;
     printChannelStatus(channel);
     printSecretRepairHint(channel);
+    console.log("Channel resource: created_or_updated");
 
     if (hasMissingRequiredSecrets(channel)) {
+      console.log("Secrets: missing");
       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");
@@ -140,27 +182,104 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
       return;
     }
 
+    console.log("Secrets: validated");
+
     if (channel.type === "telegram") {
       const setup = await applyTelegramWebhook(channel, args.flags.api);
       channel = setup.channel ?? channel;
+      console.log("Telegram setWebhook: OK");
       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})` : ""}`);
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
       printTelegramHumanNextStep(channel.name, setup.setup?.bot_username);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (channel.type === "whatsapp" && channel.provider === "uazapi") {
+      const setup = await applyProviderWebhook(channel, args.flags.api);
+      channel = setup.channel ?? channel;
+      console.log("UAZAPI webhook setup: OK");
+      console.log("UAZAPI webhook confirmed.");
+      if (setup.setup?.webhook_count !== undefined) {
+        console.log(`UAZAPI webhooks: ${setup.setup.webhook_count}`);
+      }
+
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
+      printUazapiHumanNextStep(channel);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (channel.type === "whatsapp" && channel.provider === "evolution") {
+      const setup = await applyProviderWebhook(channel, args.flags.api);
+      channel = setup.channel ?? channel;
+      console.log("Evolution webhook setup: OK");
+      console.log("Evolution webhook confirmed.");
+
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
+      printEvolutionHumanNextStep(channel);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (channel.type === "discord") {
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
+      printDiscordHumanNextStep(channel);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (channel.type === "slack") {
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
+      printSlackHumanNextStep(channel);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (channel.type === "webhook") {
+      if (channel.direction === "outbound") {
+        console.log("Outbound webhook: configured");
+        console.log(`Next human step: make sure ${channel.url_secret ?? "the webhook URL secret"} is set as a managed secret.`);
+        return;
+      }
+
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
+      printGenericWebhookHumanNextStep(channel);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
       return;
     }
 
-    if (channel.type === "whatsapp") {
+    if (channel.type === "whatsapp" && channel.provider === "zapster") {
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
+      console.log(`Next human step: paste ${channel.webhook_url} into ${channel.provider}'s webhook settings.`);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
+    } else 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})` : ""}`);
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
       console.log(`Next human step: use ${channel.webhook_url} from your website client.`);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
     }
     return;
   }
@@ -182,8 +301,38 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
         console.log(`Setup: call Telegram setWebhook with ${channel.webhook_url}`);
         console.log("Use --apply to mutate Telegram webhook settings.");
       }
+    } else if (channel.type === "whatsapp" && channel.provider === "uazapi") {
+      if (args.flags.apply) {
+        const setup = await applyProviderWebhook(channel, args.flags.api);
+        console.log("UAZAPI webhook confirmed.");
+        printChannelStatus(setup.channel ?? channel);
+        printUazapiHumanNextStep(setup.channel ?? channel);
+      } else {
+        console.log(`Setup: configure UAZAPI /webhook with ${channel.webhook_url}`);
+        console.log("Use --apply to mutate UAZAPI webhook settings.");
+      }
+    } else if (channel.type === "whatsapp" && channel.provider === "evolution") {
+      if (args.flags.apply) {
+        const setup = await applyProviderWebhook(channel, args.flags.api);
+        console.log("Evolution webhook confirmed.");
+        printChannelStatus(setup.channel ?? channel);
+        printEvolutionHumanNextStep(setup.channel ?? channel);
+      } else {
+        console.log(`Setup: configure Evolution /webhook/set/{instance} with ${channel.webhook_url}`);
+        console.log("Use --apply to mutate Evolution webhook settings.");
+      }
     } else if (channel.type === "whatsapp") {
       console.log(`Next step: paste this URL into ${channel.provider}'s webhook settings.`);
+    } else if (channel.type === "discord") {
+      printDiscordHumanNextStep(channel);
+    } else if (channel.type === "slack") {
+      printSlackHumanNextStep(channel);
+    } else if (channel.type === "webhook") {
+      if (channel.direction === "outbound") {
+        console.log("Outbound webhook endpoint: configured from managed secrets.");
+      } else {
+        printGenericWebhookHumanNextStep(channel);
+      }
     } 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.");
@@ -225,9 +374,32 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
       throw new Error('Usage: agentkit channels test <name> [--message "hello"] [--fixture <path>]');
     }
 
+    const channel = await resolveCloudChannelByName(first, args.flags.api);
+    if (channel.type === "webhook" && channel.direction === "outbound") {
+      throw new Error("Outbound webhook channels do not have an inbound test endpoint. Test them through a source channel that routes replies to this channel.");
+    }
+    const apiUrl = parseCloudApiUrl(args.flags.api);
+    const signed = channel.type === "whatsapp" && channel.provider === "evolution" && !args.flags.fixture
+      ? await runServerGeneratedChannelTest(channel, apiUrl, args.flags.message)
+      : await runServerSignedChannelTest(channel, apiUrl, await channelTestBody(channel, args.flags.message, args.flags.fixture));
+    const response = signed.response;
+    const payload = signed.payload;
+
+    console.log(JSON.stringify(payload, null, 2));
+    if (!response.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (subcommand === "test-audio") {
+    if (!first) {
+      throw new Error("Usage: agentkit channels test-audio <name> [--fixture voice-note|audio-file|<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 body = await channelAudioTestBody(channel, args.flags.fixture);
     const signed = await runServerSignedChannelTest(channel, apiUrl, body);
     const response = signed.response;
     const payload = signed.payload;
@@ -286,27 +458,77 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     }
   }
 
+  if (subcommand === "buffers") {
+    if (first === "list") {
+      if (!second) {
+        throw new Error("Usage: agentkit channels buffers list <name>");
+      }
+
+      const channel = await resolveCloudChannelByName(second, args.flags.api);
+      const response = await cloudGet<{ buffers: CloudChannelBuffer[] }>(
+        parseCloudApiUrl(args.flags.api),
+        `/v1/channels/${encodeURIComponent(channel.id)}/buffers`,
+      );
+      printChannelBuffers(response.buffers);
+      return;
+    }
+
+    if (first === "show") {
+      if (!second) {
+        throw new Error("Usage: agentkit channels buffers show [<name>] <conversation-id>");
+      }
+
+      const target = await resolveChannelBufferTarget(second, third, args.flags.api);
+      const response = await cloudGet<{ buffer: CloudChannelBuffer }>(
+        parseCloudApiUrl(args.flags.api),
+        `/v1/channels/${encodeURIComponent(target.channel.id)}/buffers/${encodeURIComponent(target.conversationId)}`,
+      );
+      console.log(JSON.stringify(response.buffer, null, 2));
+      return;
+    }
+
+    if (first === "flush" || first === "clear" || first === "retry") {
+      if (!second) {
+        throw new Error(`Usage: agentkit channels buffers ${first} [<name>] <conversation-id>`);
+      }
+
+      const target = await resolveChannelBufferTarget(second, third, args.flags.api);
+      const response = await cloudPost<ChannelBufferActionResponse>(
+        parseCloudApiUrl(args.flags.api),
+        `/v1/channels/${encodeURIComponent(target.channel.id)}/buffers/${encodeURIComponent(target.conversationId)}/${first}`,
+        {},
+      );
+      printChannelBufferAction(first, response);
+      return;
+    }
+  }
+
   throw new Error(
-    "Usage: agentkit channels list | add | connect | setup | status | doctor | test | deliveries list | deliveries show",
+    "Usage: agentkit channels list | add | connect | setup | status | doctor | test | test-audio | deliveries list | deliveries show | buffers list | buffers show | buffers flush | buffers clear | buffers retry",
   );
 }
 
 async function createHostedChannel(
-  type: "website" | "telegram" | "whatsapp",
+  type: "website" | "telegram" | "whatsapp" | "discord" | "slack" | "webhook",
   name: string,
   providerFlag: string | boolean | undefined,
+  modeFlag: 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 mode = discordModeForCli(type, modeFlag, localChannel);
   const payload = {
     name,
     type,
     provider,
-    secrets: localChannel?.secrets ?? defaultChannelSecretsForCli(type, provider),
+    ...(mode ? { mode } : {}),
+    secrets: localChannel?.secrets ?? defaultChannelSecretsForCli(type, provider, mode),
     ...(localChannel?.limits ? { limits: channelLimitsForApi(localChannel.limits) } : {}),
     ...(localChannel?.buffer ? { buffer: localChannel.buffer } : {}),
+    ...(localChannel?.audio ? { audio: localChannel.audio } : {}),
+    ...channelExtraConfigForApi(localChannel),
   };
 
   return cloudPost<{ channel: CloudChannel }>(
@@ -321,8 +543,10 @@ async function runChannelSmoke(
   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);
+  const apiUrl = parseCloudApiUrl(apiFlag);
+  const { response, payload } = channel.type === "whatsapp" && channel.provider === "evolution"
+    ? await runServerGeneratedChannelTest(channel, apiUrl, messageFlag)
+    : await runServerSignedChannelTest(channel, apiUrl, await channelTestBody(channel, messageFlag, undefined));
 
   if (!response.ok) {
     throw new Error(readCloudError(payload, response.status));
@@ -338,6 +562,49 @@ async function runChannelSmoke(
   return { status: "unknown" };
 }
 
+async function runServerGeneratedChannelTest(
+  channel: CloudChannel,
+  apiUrl: string,
+  messageFlag: string | boolean | undefined,
+): Promise<{ response: Response; payload: unknown }> {
+  const body: Record<string, unknown> = {};
+
+  if (typeof messageFlag === "string") {
+    body.message = messageFlag;
+  }
+
+  const response = await cloudFetch(apiUrl, `/v1/channels/${encodeURIComponent(channel.id)}/test`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok && isUnsupportedChannelTestRoute(payload)) {
+    return runLocallySignedChannelTest(
+      channel,
+      apiUrl,
+      await channelTestBody(channel, messageFlag, undefined),
+    );
+  }
+
+  return { response, payload };
+}
+
+async function runConnectSmoke(
+  run: () => Promise<{ status: string; delivery_id?: string }>,
+): Promise<{ status: string; delivery_id?: string } | null> {
+  try {
+    const smoke = await run();
+    console.log(`Synthetic smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+    return smoke;
+  } catch (error) {
+    console.log("Synthetic smoke: failed");
+    console.log(`  ${formatCommandError(error)}`);
+    return null;
+  }
+}
+
 async function runServerSignedChannelTest(
   channel: CloudChannel,
   apiUrl: string,
@@ -362,8 +629,22 @@ async function runLocallySignedChannelTest(
   apiUrl: string,
   rawBody: string,
 ): Promise<{ response: Response; payload: unknown }> {
-  const path = new URL(channel.webhook_url).pathname;
-  const headers = channelTestHeaders(channel);
+  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 ?? "");
+  }
+
+  if (channel.required_secrets.some((secret) => secret.name === "UAZAPI_WEBHOOK_TOKEN")) {
+    webhookUrl.searchParams.set("token", process.env.UAZAPI_WEBHOOK_TOKEN ?? "");
+  }
+
+  if (channel.required_secrets.some((secret) => secret.name === "EVOLUTION_WEBHOOK_TOKEN")) {
+    webhookUrl.searchParams.set("token", process.env.EVOLUTION_WEBHOOK_TOKEN ?? "");
+  }
+
+  const path = `${webhookUrl.pathname}${webhookUrl.search}`;
+  const headers = channelTestHeaders(channel, rawBody);
   const response = await cloudFetch(apiUrl, path, {
     method: "POST",
     headers,
@@ -465,6 +746,17 @@ async function applyTelegramWebhook(
   };
 }
 
+async function applyProviderWebhook(
+  channel: CloudChannel,
+  apiFlag: string | boolean | undefined,
+): Promise<ChannelSetupResponse> {
+  return cloudPost<ChannelSetupResponse>(
+    parseCloudApiUrl(apiFlag),
+    `/v1/channels/${encodeURIComponent(channel.id)}/setup`,
+    {},
+  );
+}
+
 function shouldFallbackToLocalTelegramSetup(error: unknown): boolean {
   if (!(error instanceof Error)) {
     return false;
@@ -510,14 +802,80 @@ function printTelegramHumanNextStep(channelName: string, botUsername: string | u
   console.log(`  Then run: npm run agentkit -- channels deliveries list ${channelName}`);
 }
 
+function printUazapiHumanNextStep(channel: CloudChannel): void {
+  console.log("");
+  console.log("Next human step:");
+  console.log("  Confirm the UAZAPI instance is connected to WhatsApp");
+  console.log('  Send "hello" from a real WhatsApp contact');
+  console.log(`  Then run: npm run agentkit -- channels deliveries list ${channel.name}`);
+}
+
+function printEvolutionHumanNextStep(channel: CloudChannel): void {
+  console.log("");
+  console.log("Next human step:");
+  console.log("  Confirm the Evolution API instance is connected to WhatsApp");
+  console.log('  Send "hello" from a real WhatsApp contact');
+  console.log(`  Then run: npm run agentkit -- channels deliveries list ${channel.name}`);
+}
+
+function printDiscordHumanNextStep(channel: CloudChannel): void {
+  console.log("");
+  console.log("Next human step:");
+
+  if (channel.mode === "bot") {
+    console.log("  Open the Discord Developer Portal for your application");
+    console.log("  Bot page: enable Message Content Intent");
+    console.log("  Installation page: install the app into your server with bot permissions");
+    console.log("  Grant the bot View Channel, Read Message History, and Send Messages in the channels it should answer");
+    console.log('  Send "hello" in an allowed server channel');
+    console.log(`  Then run: npm run agentkit -- channels deliveries list ${channel.name}`);
+    return;
+  }
+
+  console.log("  Open the Discord Developer Portal for your application");
+  console.log(`  Paste ${channel.webhook_url} into Interactions Endpoint URL`);
+  console.log("  Register a slash command with a string option named message, text, prompt, question, query, or input");
+  console.log(`  Then run: npm run agentkit -- channels deliveries list ${channel.name}`);
+}
+
+function printSlackHumanNextStep(channel: CloudChannel): void {
+  console.log("");
+  console.log("Next human step:");
+  console.log("  Open the Slack app configuration");
+  console.log("  Event Subscriptions: enable events");
+  console.log(`  Request URL: paste ${channel.webhook_url}`);
+  console.log("  Subscribe to bot events: app_mention and message.im");
+  console.log("  OAuth scopes: app_mentions:read, im:history, chat:write");
+  console.log("  Install or reinstall the app to the workspace");
+  console.log('  Mention the app with "hello" or send it a direct message');
+  console.log(`  Then run: npm run agentkit -- channels deliveries list ${channel.name}`);
+}
+
+function printGenericWebhookHumanNextStep(channel: CloudChannel): void {
+  console.log("");
+  console.log("Next human step:");
+  console.log(`  Point n8n, Make, Zapier, or your server to ${channel.webhook_url}`);
+  console.log("  Send JSON with event_id, external_id, and message");
+  console.log("  Authenticate with Authorization: Bearer <AGENTKIT_WEBHOOK_SECRET>");
+  console.log(`  Then run: npm run agentkit -- channels deliveries list ${channel.name}`);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
+function formatCommandError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 async function readDeployStateIfExists(cwd: string): Promise<DeployState | null> {
   return readLocalDeployStateIfExists(cwd);
 }
 
+function isCliChannelType(value: string): value is "website" | "telegram" | "whatsapp" | "discord" | "slack" | "webhook" {
+  return value === "website" || value === "telegram" || value === "whatsapp" || value === "discord" || value === "slack" || value === "webhook";
+}
+
 async function readDeployStateRequired(cwd: string): Promise<DeployState> {
   const state = await readDeployStateIfExists(cwd);
 
@@ -547,12 +905,21 @@ function printChannelStatus(channel: CloudChannel): void {
   }
   console.log(`Type: ${channel.type}`);
   console.log(`Provider: ${channel.provider}`);
+  if (channel.type === "discord") {
+    console.log(`Mode: ${channel.mode ?? "interactions"}`);
+  }
+  if (channel.type === "webhook" && channel.direction) {
+    console.log(`Direction: ${channel.direction}`);
+  }
   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) {
+  if (
+    channel.required_secrets.length === 0 &&
+    defaultChannelSecretsForCli(channel.type, channel.provider, channel.mode).length > 0
+  ) {
     console.log(
       `  control-plane channel metadata bug: required_secrets is empty for ${channel.type}/${channel.provider}`,
     );
@@ -573,7 +940,10 @@ function printChannelStatus(channel: CloudChannel): void {
 }
 
 function printSecretRepairHint(channel: CloudChannel): void {
-  if (channel.required_secrets.length > 0 || defaultChannelSecretsForCli(channel.type, channel.provider).length === 0) {
+  if (
+    channel.required_secrets.length > 0 ||
+    defaultChannelSecretsForCli(channel.type, channel.provider, channel.mode).length === 0
+  ) {
     return;
   }
 
@@ -583,7 +953,7 @@ function printSecretRepairHint(channel: CloudChannel): void {
 }
 
 function hasMissingRequiredSecrets(channel: CloudChannel): boolean {
-  const expected = defaultChannelSecretsForCli(channel.type, channel.provider);
+  const expected = defaultChannelSecretsForCli(channel.type, channel.provider, channel.mode);
 
   if (channel.required_secrets.length === 0 && expected.length > 0) {
     return true;
@@ -629,6 +999,16 @@ function printChannelDoctor(report: ChannelDoctorReport): void {
     `  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.buffers.length > 0) {
+    console.log("");
+    console.log("Buffers:");
+    for (const buffer of report.buffers) {
+      console.log(
+        `  ${buffer.conversation_id}: ${buffer.status} messages=${buffer.buffered_message_count} stale=${buffer.stale ? "yes" : "no"}`,
+      );
+    }
+  }
+
   if (report.probable_error) {
     console.log("");
     console.log(`Probable error: ${report.probable_error}`);
@@ -654,19 +1034,119 @@ function formatCheckStatus(status: ChannelDoctorReport["checks"][number]["status
   return "UNKNOWN";
 }
 
+function printChannelBuffers(buffers: CloudChannelBuffer[]): void {
+  if (buffers.length === 0) {
+    console.log("No channel buffers found.");
+    return;
+  }
+
+  console.log("CONVERSATION\tSTATUS\tMESSAGES\tCHARS\tSTALE\tAVAILABLE_AT\tJOB");
+  for (const buffer of buffers) {
+    console.log(
+      [
+        buffer.conversation_id,
+        buffer.status,
+        String(buffer.buffered_message_count),
+        String(buffer.buffered_char_count),
+        buffer.stale ? "yes" : "no",
+        buffer.available_at ?? "",
+        buffer.job_id ?? "",
+      ].join("\t"),
+    );
+  }
+}
+
+function printChannelBufferAction(action: string, response: ChannelBufferActionResponse): void {
+  const conversationId = response.buffer?.conversation_id ?? response.job?.conversation_id ?? "unknown";
+
+  if (action === "flush") {
+    console.log(
+      response.job
+        ? `Flushed buffer ${conversationId}; queued job ${response.job.id}.`
+        : `No queued buffer was flushed for ${conversationId}.`,
+    );
+    return;
+  }
+
+  if (action === "clear") {
+    console.log(
+      response.cleared
+        ? `Cleared buffer ${conversationId}.`
+        : `No queued buffer was cleared for ${conversationId}.`,
+    );
+    return;
+  }
+
+  console.log(
+    response.retried && response.job
+      ? `Retried channel job ${response.job.id} for ${conversationId}.`
+      : `No failed or dead-lettered job was retried for ${conversationId}.`,
+  );
+}
+
 async function resolveCloudChannelByName(name: string, apiFlag: string | boolean | undefined): Promise<CloudChannel> {
+  const channels = await listCloudChannelsForCurrentDeploy(apiFlag);
+  const channel = channels.find((candidate) => candidate.name === name);
+
+  if (!channel) {
+    const deployState = await readDeployStateRequired(process.cwd());
+    throw new Error(`Channel "${name}" was not found for deploy ${deployState.deploy_id}.`);
+  }
+
+  return channel;
+}
+
+async function listCloudChannelsForCurrentDeploy(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 response.channels;
+}
+
+async function resolveChannelBufferTarget(
+  first: string,
+  second: string | undefined,
+  apiFlag: string | boolean | undefined,
+): Promise<{ channel: CloudChannel; conversationId: string }> {
+  if (second) {
+    return {
+      channel: await resolveCloudChannelByName(first, apiFlag),
+      conversationId: second,
+    };
   }
 
-  return channel;
+  const conversationId = first;
+  const channels = await listCloudChannelsForCurrentDeploy(apiFlag);
+  const matches: CloudChannel[] = [];
+
+  for (const channel of channels) {
+    const response = await cloudGet<{ buffers: CloudChannelBuffer[] }>(
+      parseCloudApiUrl(apiFlag),
+      `/v1/channels/${encodeURIComponent(channel.id)}/buffers`,
+    );
+
+    if (response.buffers.some((buffer) => buffer.conversation_id === conversationId)) {
+      matches.push(channel);
+    }
+  }
+
+  if (matches.length === 1) {
+    return {
+      channel: matches[0],
+      conversationId,
+    };
+  }
+
+  if (matches.length > 1) {
+    throw new Error(
+      `Conversation ${conversationId} has buffers in multiple channels. Use: agentkit channels buffers show <name> ${conversationId}`,
+    );
+  }
+
+  throw new Error(`No channel buffer found for conversation ${conversationId}.`);
 }
 
 function channelProviderForCli(type: string, providerFlag: string | boolean | undefined): string {
@@ -678,16 +1158,60 @@ function channelProviderForCli(type: string, providerFlag: string | boolean | un
     return "telegram";
   }
 
+  if (type === "discord") {
+    return "discord";
+  }
+
+  if (type === "slack") {
+    if (providerFlag !== undefined) {
+      throw new Error("--provider is not supported for Slack channels.");
+    }
+
+    return "slack";
+  }
+
+  if (type === "webhook") {
+    if (providerFlag !== undefined) {
+      throw new Error("--provider is not supported for generic webhook channels.");
+    }
+
+    return "generic";
+  }
+
   const provider = providerFlag ?? "zapster";
 
-  if (provider !== "zapster" && provider !== "meta") {
-    throw new Error('WhatsApp provider must be "zapster" or "meta".');
+  if (provider !== "zapster" && provider !== "meta" && provider !== "uazapi" && provider !== "evolution") {
+    throw new Error('WhatsApp provider must be "zapster", "meta", "uazapi", or "evolution".');
   }
 
   return provider;
 }
 
-function defaultChannelSecretsForCli(type: string, provider: string): string[] {
+function discordModeForCli(
+  type: string,
+  modeFlag: string | boolean | undefined,
+  localChannel: AgentChannel | null,
+): "interactions" | "bot" | undefined {
+  if (type !== "discord") {
+    if (modeFlag !== undefined) {
+      throw new Error("--mode is only supported for Discord channels.");
+    }
+
+    return undefined;
+  }
+
+  if (modeFlag !== undefined) {
+    if (modeFlag !== "interactions" && modeFlag !== "bot") {
+      throw new Error('Discord mode must be "interactions" or "bot".');
+    }
+
+    return modeFlag;
+  }
+
+  return localChannel?.type === "discord" ? localChannel.mode : "interactions";
+}
+
+function defaultChannelSecretsForCli(type: string, provider: string, mode?: "interactions" | "bot"): string[] {
   if (type === "website") {
     return ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"];
   }
@@ -697,16 +1221,49 @@ function defaultChannelSecretsForCli(type: string, provider: string): string[] {
   }
 
   if (type === "whatsapp" && provider === "zapster") {
-    return ["ZAPSTER_API_KEY", "ZAPSTER_WEBHOOK_SECRET"];
+    return ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID", "ZAPSTER_WEBHOOK_TOKEN"];
   }
 
   if (type === "whatsapp" && provider === "meta") {
     return ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"];
   }
 
+  if (type === "whatsapp" && provider === "uazapi") {
+    return ["UAZAPI_BASE_URL", "UAZAPI_TOKEN", "UAZAPI_WEBHOOK_TOKEN"];
+  }
+
+  if (type === "whatsapp" && provider === "evolution") {
+    return ["EVOLUTION_API_BASE_URL", "EVOLUTION_API_KEY", "EVOLUTION_INSTANCE_NAME", "EVOLUTION_WEBHOOK_TOKEN"];
+  }
+
+  if (type === "discord") {
+    return mode === "bot" ? ["DISCORD_BOT_TOKEN"] : ["DISCORD_PUBLIC_KEY"];
+  }
+
+  if (type === "slack") {
+    return ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"];
+  }
+
+  if (type === "webhook") {
+    return ["AGENTKIT_WEBHOOK_SECRET"];
+  }
+
   return [];
 }
 
+function channelExtraConfigForApi(channel: AgentChannel | null): Record<string, unknown> {
+  if (!channel) {
+    return {};
+  }
+
+  return {
+    ...("direction" in channel && channel.direction ? { direction: channel.direction } : {}),
+    ...(channel.replyTo ? { reply_to: channel.replyTo } : {}),
+    ...("urlSecret" in channel && channel.urlSecret ? { url_secret: channel.urlSecret } : {}),
+    ...("auth" in channel && channel.auth ? { auth: channel.auth } : {}),
+  };
+}
+
 async function readLocalChannelConfig(
   cwd: string,
   type: string,
@@ -754,6 +1311,45 @@ async function channelTestBody(
     });
   }
 
+  if (channel.type === "whatsapp" && channel.provider === "uazapi") {
+    return JSON.stringify({
+      EventType: "messages",
+      event: "messages",
+      message: {
+        id: `uaz_msg_${Date.now()}`,
+        messageid: `uaz_wamid_${Date.now()}`,
+        chatid: "5511999999999@s.whatsapp.net",
+        sender: "5511999999999@s.whatsapp.net",
+        senderName: "AgentKit",
+        fromMe: false,
+        wasSentByApi: false,
+        messageType: "text",
+        text: message,
+        messageTimestamp: Date.now(),
+      },
+    });
+  }
+
+  if (channel.type === "whatsapp" && channel.provider === "evolution") {
+    return JSON.stringify({
+      event: "MESSAGES_UPSERT",
+      instance: process.env.EVOLUTION_INSTANCE_NAME ?? "local",
+      data: {
+        key: {
+          remoteJid: "5511999999999@s.whatsapp.net",
+          fromMe: false,
+          id: `evo_wamid_${Date.now()}`,
+        },
+        pushName: "AgentKit",
+        messageType: "conversation",
+        message: {
+          conversation: message,
+        },
+        messageTimestamp: Math.floor(Date.now() / 1000),
+      },
+    });
+  }
+
   if (channel.type === "whatsapp") {
     return JSON.stringify({
       event_id: `evt_${Date.now()}`,
@@ -767,6 +1363,85 @@ async function channelTestBody(
     });
   }
 
+  if (channel.type === "discord") {
+    if (channel.mode === "bot") {
+      return JSON.stringify({
+        id: `discord_message_${Date.now()}`,
+        guild_id: "agentkit_guild",
+        channel_id: "agentkit_channel",
+        author: {
+          id: "agentkit_user",
+          username: "agentkit",
+        },
+        member: {
+          nick: "AgentKit",
+        },
+        content: message,
+        mentions: [],
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    return JSON.stringify({
+      id: `discord_interaction_${Date.now()}`,
+      application_id: "agentkit_discord_app",
+      type: 2,
+      data: {
+        id: "agentkit_command",
+        name: "ask",
+        type: 1,
+        options: [
+          {
+            name: "message",
+            type: 3,
+            value: message,
+          },
+        ],
+      },
+      guild_id: "agentkit_guild",
+      channel_id: "agentkit_channel",
+      member: {
+        user: {
+          id: "agentkit_user",
+          username: "agentkit",
+        },
+      },
+      token: `agentkit_interaction_token_${Date.now()}`,
+      version: 1,
+    });
+  }
+
+  if (channel.type === "slack") {
+    const now = Date.now();
+
+    return JSON.stringify({
+      token: "deprecated-verification-token",
+      team_id: "T_AGENTKIT",
+      api_app_id: "A_AGENTKIT",
+      type: "event_callback",
+      event_id: `Ev${now}`,
+      event_time: Math.floor(now / 1000),
+      event: {
+        type: "app_mention",
+        user: "UAGENTKITUSER",
+        text: `<@UAGENTKITBOT> ${message}`,
+        ts: `${Math.floor(now / 1000)}.000100`,
+        channel: "C_AGENTKIT",
+        event_ts: `${Math.floor(now / 1000)}.000100`,
+      },
+      authorizations: [],
+      is_ext_shared_channel: false,
+    });
+  }
+
+  if (channel.type === "webhook") {
+    return JSON.stringify({
+      event_id: `evt_${Date.now()}`,
+      external_id: "agentkit-webhook-test",
+      message,
+    });
+  }
+
   return JSON.stringify({
     event_id: `web_${Date.now()}`,
     visitor_id: "visitor_test",
@@ -777,7 +1452,127 @@ async function channelTestBody(
   });
 }
 
-function channelTestHeaders(channel: CloudChannel): Headers {
+async function channelAudioTestBody(
+  channel: CloudChannel,
+  fixtureFlag: string | boolean | undefined,
+): Promise<string> {
+  if (typeof fixtureFlag === "string" && isExplicitFixturePath(fixtureFlag)) {
+    return readFile(resolve(process.cwd(), fixtureFlag), "utf8");
+  }
+
+  const fixture = typeof fixtureFlag === "string" ? fixtureFlag : "voice-note";
+
+  if (channel.type === "telegram") {
+    if (fixture !== "voice-note" && fixture !== "telegram-voice-note" && fixture !== "telegram-audio-message") {
+      throw new Error('Telegram audio smoke supports --fixture voice-note or --fixture telegram-voice-note.');
+    }
+
+    return JSON.stringify({
+      update_id: Date.now(),
+      message: {
+        message_id: 1,
+        date: Math.floor(Date.now() / 1000),
+        chat: { id: 456, type: "private" },
+        from: { id: 123, first_name: "AgentKit" },
+        voice: {
+          file_id: `agentkit_voice_${Date.now()}`,
+          file_unique_id: `agentkit_voice_unique_${Date.now()}`,
+          duration: 12,
+          mime_type: "audio/ogg",
+          file_size: 42,
+        },
+      },
+    });
+  }
+
+  if (channel.type === "whatsapp" && channel.provider === "zapster") {
+    if (fixture !== "voice-note" && fixture !== "audio-file" && fixture !== "zapster-audio" && fixture !== "zapster-audio-message") {
+      throw new Error('Zapster audio smoke supports --fixture voice-note, --fixture audio-file, or --fixture zapster-audio.');
+    }
+
+    return JSON.stringify({
+      event_id: `zap_evt_audio_${Date.now()}`,
+      instance_id: "local",
+      message: {
+        id: `wamid.audio.${Date.now()}`,
+        from: "5511999999999",
+        type: "audio",
+        audio: {
+          id: `media_audio_${Date.now()}`,
+          url: `https://api.zapsterapi.com/media/audio/media_audio_${Date.now()}.ogg`,
+          mime_type: "audio/ogg",
+          duration: 12,
+          file_size: 42,
+          ...(fixture === "voice-note" ? { ptt: "true" } : {}),
+        },
+      },
+    });
+  }
+
+  if (channel.type === "whatsapp" && channel.provider === "uazapi") {
+    if (fixture !== "voice-note" && fixture !== "audio-file" && fixture !== "uazapi-audio" && fixture !== "uazapi-audio-message") {
+      throw new Error('UAZAPI audio smoke supports --fixture voice-note, --fixture audio-file, or --fixture uazapi-audio.');
+    }
+
+    return JSON.stringify({
+      EventType: "messages",
+      event: "messages",
+      message: {
+        id: `uaz_audio_${Date.now()}`,
+        messageid: `uaz_wamid_audio_${Date.now()}`,
+        chatid: "5511999999999@s.whatsapp.net",
+        sender: "5511999999999@s.whatsapp.net",
+        senderName: "AgentKit",
+        fromMe: false,
+        wasSentByApi: false,
+        messageType: fixture === "voice-note" ? "ptt" : "audio",
+        mimetype: "audio/ogg",
+        duration: 12,
+        file_size: 42,
+        messageTimestamp: Date.now(),
+      },
+    });
+  }
+
+  if (channel.type === "whatsapp" && channel.provider === "evolution") {
+    if (fixture !== "voice-note" && fixture !== "audio-file" && fixture !== "evolution-audio" && fixture !== "evolution-audio-message") {
+      throw new Error(
+        'Evolution audio smoke supports --fixture voice-note, --fixture audio-file, --fixture evolution-audio, or --fixture evolution-audio-message.',
+      );
+    }
+
+    return JSON.stringify({
+      event: "MESSAGES_UPSERT",
+      instance: process.env.EVOLUTION_INSTANCE_NAME ?? "local",
+      data: {
+        key: {
+          remoteJid: "5511999999999@s.whatsapp.net",
+          fromMe: false,
+          id: `evo_wamid_audio_${Date.now()}`,
+        },
+        pushName: "AgentKit",
+        messageType: "audioMessage",
+        message: {
+          audioMessage: {
+            mimetype: "audio/ogg",
+            seconds: 12,
+            ptt: fixture === "voice-note",
+            fileLength: 42,
+          },
+        },
+        messageTimestamp: Math.floor(Date.now() / 1000),
+      },
+    });
+  }
+
+  throw new Error(`Audio smoke is not supported for ${channel.type}/${channel.provider}.`);
+}
+
+function isExplicitFixturePath(value: string): boolean {
+  return value.includes("/") || value.startsWith(".") || value.endsWith(".json");
+}
+
+function channelTestHeaders(channel: CloudChannel, rawBody: string): Headers {
   const headers = new Headers({ "Content-Type": "application/json" });
 
   if (channel.type === "website") {
@@ -793,7 +1588,32 @@ function channelTestHeaders(channel: CloudChannel): Headers {
   }
 
   if (channel.type === "whatsapp" && channel.provider === "zapster") {
-    headers.set("X-Zapster-Webhook-Secret", process.env.ZAPSTER_WEBHOOK_SECRET ?? "");
+    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");
+  }
+
+  if (channel.type === "slack") {
+    const signingSecret = process.env.SLACK_SIGNING_SECRET;
+
+    if (signingSecret) {
+      const timestamp = String(Math.floor(Date.now() / 1000));
+      const signature = createHmac("sha256", signingSecret)
+        .update(`v0:${timestamp}:${rawBody}`)
+        .digest("hex");
+      headers.set("X-Slack-Request-Timestamp", timestamp);
+      headers.set("X-Slack-Signature", `v0=${signature}`);
+    }
+  }
+
+  if (channel.type === "webhook") {
+    const secret = process.env.AGENTKIT_WEBHOOK_SECRET;
+
+    if (secret) {
+      headers.set("Authorization", `Bearer ${secret}`);
+    }
   }
 
   return headers;