@andreprado/agentkit 0.1.0-alpha.11 → 0.1.0-alpha.13

package/docs/guides/add-channel.md

@@ -21,6 +21,7 @@ agentkit channels setup support-telegram
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"
 agentkit channels deliveries list support-telegram
+agentkit channels buffers list support-telegram
 ```
 
 Use `--api <url>` with hosted commands when testing against a non-default AgentKit Cloud API.
@@ -76,6 +77,16 @@ Buffering is scoped to one channel conversation. AgentKit still validates and de
 
 Use `buffer: { mode: "off" }` or omit `buffer` to process each inbound message as its own agent run.
 
+Buffer controls:
+
+```sh
+agentkit channels buffers list support-whatsapp
+agentkit channels buffers show support-whatsapp <conversation-id>
+agentkit channels buffers flush support-whatsapp <conversation-id>
+agentkit channels buffers clear support-whatsapp <conversation-id>
+agentkit channels buffers retry support-whatsapp <conversation-id>
+```
+
 ## Safety Rules
 
 - Never put provider token values in `agentkit.config.ts`.
@@ -93,9 +104,11 @@ agentkit inspect
 agentkit channels list
 agentkit channels test support-telegram --message "hello"
 agentkit channels deliveries list support-telegram
+agentkit channels buffers list support-telegram
 ```
 
 Expected hosted status includes `NAME`, `TYPE`, `PROVIDER`, `STATUS`, and `LAST_EVENT`. Secret output is name plus `set` or `missing`, never the value.
+Outbound provider success is `provider_sent`. Explicit dry-run mode is `adapter_stubbed`, which means the provider was not called.
 
 ## Troubleshooting
 

package/docs/guides/agentkit-skills-architecture.md

@@ -351,6 +351,7 @@ Do not ship these into user capsules by default:
 - account grant/revoke;
 - backend contract implementation;
 - Cloudflare/Turso/R2 provisioning internals;
+- release-lane ownership;
 - package publishing.
 
 Those workflows belong in maintainer skills inside the AgentKit repository, not in generated user capsules.

package/docs/guides/channel-security.md

@@ -27,7 +27,7 @@ AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
 
 Telegram smoke also requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
 
-Zapster smoke also requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+Zapster smoke also requires `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `AGENTKIT_ZAPSTER_TO`. `AGENTKIT_ZAPSTER_SEND_URL` is optional and defaults to `https://api.zapsterapi.com/v1/wa/messages`.
 
 ## Files Created Or Edited
 

package/docs/guides/channels-implementation-map.md

@@ -154,7 +154,7 @@ Add:
 - `GET /v1/deploys/{deploy_id}/channels`;
 - `GET /v1/channels/{channel_id}`;
 - `DELETE /v1/channels/{channel_id}`;
-- public webhook routes for `/channels/{channel_id}/{type}/{provider}/webhook`;
+- public webhook routes for `/channels/{channel_name}/{type}/{provider}/webhook`, with old `chn_*` routes accepted for compatibility;
 - delivery inspection routes for CLI use.
 
 The local `npm run agentkit:operator -- serve` path can use an in-memory or local SQLite fake store first. Production Postgres support can follow once the contract is tested. In both stores, persist only secret names and statuses, never secret values.
@@ -192,7 +192,7 @@ Use this boundary for V1 local cloud tests:
 | --- | --- | --- |
 | Channel resource metadata | Yes: `channels` table or equivalent fake store keyed by `chn_...`. | Read-only manifest input after deploy. |
 | Channel secret references | Yes: names and `set`/`missing` status only. | Runtime receives injected secret values by name; no readback. |
-| Channel endpoint URL | Yes: generated from deploy URL plus stable channel ID. | Worker routes requests by channel ID, type, and provider. |
+| Channel endpoint URL | Yes: generated from deploy URL plus stable channel name. | Worker forwards deploy ID and routes requests by channel name, type, and provider; old `chn_*` URLs remain compatibility routes. |
 | Channel delivery records | Yes: `deliveries` table keyed by `del_...` for CLI inspection. | Worker/consumer reports state transitions back to control plane or durable storage. |
 | Channel event audit records | Yes: compact event records keyed by `chevt_...`, with redacted provider metadata. | Ingress creates or reports event records after provider validation. |
 | External identity mappings | Fake DO-compatible store for local tests, keyed by `chid_...`. | Durable Object owns strongly consistent identity to conversation mapping. |

package/docs/guides/channels-production-handoff.md

@@ -44,7 +44,7 @@ META_WHATSAPP_VERIFY_TOKEN
 agentkit channels add telegram support-telegram
 agentkit channels add whatsapp support-whatsapp --provider zapster
 agentkit channels setup support-telegram --apply
-agentkit channels setup support-whatsapp
+agentkit channels connect whatsapp support-whatsapp --provider zapster
 ```
 
 5. Run smoke checks:
@@ -55,6 +55,21 @@ agentkit channels test support-telegram --message "hello"
 agentkit channels status support-whatsapp
 agentkit channels test support-whatsapp --message "hello"
 agentkit channels deliveries list support-telegram --since 1h
+agentkit channels deliveries list support-whatsapp --since 1h
+agentkit channels buffers list support-whatsapp
+```
+
+After deploy, record this exact handoff block:
+
+```txt
+Deploy URL: https://<deploy-host>
+Telegram channel URL: https://<deploy-host>/channels/support-telegram/telegram/telegram/webhook
+Zapster channel URL: https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook
+Required provider webhook settings: Telegram setWebhook URL/secret token; Zapster webhook URL plus optional ZAPSTER_WEBHOOK_TOKEN query parameter
+Required managed secrets: TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET, ZAPSTER_API_KEY, ZAPSTER_INSTANCE_ID, ZAPSTER_WEBHOOK_ID
+Smoke commands: agentkit channels doctor <name>; agentkit channels test <name> --message "hello"; agentkit channels deliveries list <name> --since 1h
+Rollback command: curl -X DELETE "$AGENTKIT_CLOUD_API_URL/v1/channels/<channel-id>" -H "Authorization: Bearer $AGENTKIT_CLOUD_API_TOKEN"; then remove provider webhook registration before rolling back the Worker
+Known unverified items: any channel with no real provider inbound, no provider_sent outbound, stale buffers, or AGENTKIT_CHANNEL_SEND_DRY_RUN=1
 ```
 
 ## Local Fake Versus Real Provider Gates
@@ -74,7 +89,7 @@ AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
 
 Telegram smoke requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
 
-Zapster smoke requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+Zapster smoke requires `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `AGENTKIT_ZAPSTER_TO`. `AGENTKIT_ZAPSTER_SEND_URL` is optional and defaults to `https://api.zapsterapi.com/v1/wa/messages`.
 
 ## Smoke Checks
 
@@ -82,6 +97,7 @@ Zapster smoke requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGEN
 - Invalid Telegram signature or Zapster origin headers return `401` and create a failed delivery.
 - Duplicate provider event returns `200` with `duplicate` and creates no second queue job.
 - Accepted inbound text creates one queue job and one outbound delivery.
+- Real outbound success is `provider_sent` and includes a provider message ID. `adapter_stubbed` means dry-run mode built a request but did not call the provider.
 - Buffered inbound bursts stay in `buffered` state, then flush into one queue job and one outbound delivery.
 - Retryable failures dead-letter after the configured retry ceiling.
 - `channel_limit_exceeded` does not create queue backlog.

package/docs/guides/connect-telegram.md

@@ -95,7 +95,7 @@ agentkit channels deliveries show <delivery-id>
 Expected webhook URL shape:
 
 ```txt
-https://<deploy-host>/channels/chn_<id>/telegram/webhook
+https://<deploy-host>/channels/support-telegram/telegram/telegram/webhook
 ```
 
 ## Troubleshooting

package/docs/guides/connect-whatsapp-zapster.md

@@ -12,11 +12,11 @@ Use this after `whatsappChannel({ name: "support-whatsapp", provider: "zapster"
 
 ```sh
 agentkit deploy
-agentkit channels add whatsapp support-whatsapp --provider zapster
-agentkit channels setup support-whatsapp
+agentkit channels connect whatsapp support-whatsapp --provider zapster
 agentkit channels status support-whatsapp
 agentkit channels test support-whatsapp --message "hello"
 agentkit channels deliveries list support-whatsapp --since 24h
+agentkit channels buffers list support-whatsapp
 ```
 
 Required secrets:
@@ -80,13 +80,13 @@ whatsappChannel({
 Expected webhook URL shape:
 
 ```txt
-https://<deploy-host>/channels/chn_<id>/whatsapp/zapster/webhook
+https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook
 ```
 
 If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, register the Zapster URL with the token as a query parameter:
 
 ```txt
-https://<deploy-host>/channels/chn_<id>/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>
+https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>
 ```
 
 ## Safety Rules
@@ -98,6 +98,9 @@ https://<deploy-host>/channels/chn_<id>/whatsapp/zapster/webhook?token=<ZAPSTER_
 - Use optional `ZAPSTER_WEBHOOK_TOKEN` in the webhook URL when the endpoint should require an extra secret known only to AgentKit and Zapster.
 - Unsupported media should be logged as skipped/unsupported without creating an agent run.
 - AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`.
+- Outbound replies call `POST https://api.zapsterapi.com/v1/wa/messages` with bearer auth and a JSON body containing `recipient`, `text`, and `instance_id`.
+- Real provider success is recorded as `provider_sent` only when Zapster returns a provider message ID.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Zapster should not receive a real message. Dry-run deliveries are recorded as `adapter_stubbed`, not sent.
 
 ## Verification
 
@@ -106,6 +109,10 @@ agentkit channels status support-whatsapp
 agentkit channels test support-whatsapp --message "hello"
 agentkit channels deliveries list support-whatsapp
 agentkit channels deliveries show <delivery-id>
+agentkit channels buffers list support-whatsapp
+agentkit channels buffers flush support-whatsapp <conversation-id>
+agentkit channels buffers clear support-whatsapp <conversation-id>
+agentkit channels buffers retry support-whatsapp <conversation-id>
 ```
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "private": false,
   "type": "module",
   "repository": {
@@ -20,7 +20,6 @@
     "docs",
     "!docs/guides/backend-contracts.md",
     "!docs/guides/debug-channel.md",
-    "!docs/guides/deploy-agentkit-cloud-hostinger.md",
     "README.md"
   ],
   "publishConfig": {

package/src/cli/commands/channels.ts

@@ -43,6 +43,35 @@ 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?: {
@@ -65,6 +94,7 @@ type ChannelDoctorReport = {
     message: string;
     fix?: string;
   }>;
+  buffers: CloudChannelBuffer[];
   last_delivery: {
     inbound: CloudDelivery | null;
     outbound: CloudDelivery | null;
@@ -76,7 +106,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());
@@ -154,7 +184,11 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
       return;
     }
 
-    if (channel.type === "whatsapp") {
+    if (channel.type === "whatsapp" && channel.provider === "zapster") {
+      const smoke = await runChannelSmoke(channel, args.flags.api, args.flags.message);
+      console.log(`Webhook smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+      console.log(`Next human step: paste ${channel.webhook_url} into ${channel.provider}'s webhook settings.`);
+    } 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 {
@@ -286,8 +320,53 @@ 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 | deliveries list | deliveries show | buffers list | buffers show | buffers flush | buffers clear | buffers retry",
   );
 }
 
@@ -635,6 +714,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}`);
@@ -660,19 +749,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 {

package/src/cli/help.ts

@@ -84,6 +84,11 @@ Usage:
   agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
   agentkit channels deliveries list <name> [--api <url>]
   agentkit channels deliveries show <delivery-id> [--api <url>]
+  agentkit channels buffers list <name> [--api <url>]
+  agentkit channels buffers show [<name>] <conversation-id> [--api <url>]
+  agentkit channels buffers flush [<name>] <conversation-id> [--api <url>]
+  agentkit channels buffers clear [<name>] <conversation-id> [--api <url>]
+  agentkit channels buffers retry [<name>] <conversation-id> [--api <url>]
   agentkit inspect
   agentkit build [--target cloudflare|container]
   agentkit login --token <token> [--api <url>]

package/src/runtime/channels/telegram.ts

@@ -156,7 +156,7 @@ export async function sendTelegramMessage(
 
     return {
       ok: true,
-      status: "sent",
+      status: "stubbed",
       providerRequestId: request.idempotencyKey,
       providerMetadata: {
         method: request.method,
@@ -247,11 +247,26 @@ export async function sendTelegramMessage(
   const result = isRecord(payload.result) ? payload.result : undefined;
   const messageId = readNumberishString(result ?? {}, "message_id");
 
+  if (!messageId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: "Telegram sendMessage did not return result.message_id.",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
   return {
     ok: true,
     status: "sent",
     providerRequestId: request.idempotencyKey,
-    ...(messageId ? { providerMessageId: messageId } : {}),
+    providerMessageId: messageId,
     providerMetadata: {
       method: request.method,
       url: request.url,

package/src/runtime/channels/whatsapp-zapster.ts

@@ -1,6 +1,7 @@
 import type {
   ChannelAdapter,
   ChannelSendInput,
+  ChannelSendResult,
   RawWebhookEvent,
   WebhookVerificationInput,
   WebhookVerificationResult,
@@ -140,17 +141,7 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
     ];
   },
   async sendMessage(input) {
-    const request = buildZapsterSendMessageRequest(input);
-
-    return {
-      ok: true,
-      status: "sent",
-      providerRequestId: request.idempotencyKey,
-      providerMetadata: {
-        method: request.method,
-        url: request.url,
-      },
-    };
+    return sendZapsterMessage(input);
   },
   getStatus(input) {
     const missingSecrets = ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"].filter(
@@ -248,16 +239,152 @@ export type ZapsterSendMessageRequest = {
   method: "POST";
   url: string;
   body: {
-    to: string;
-    type: "text";
-    text: {
-      body: string;
-    };
+    recipient: string;
+    text: string;
+    instance_id: string;
   };
   idempotencyKey: string;
 };
 
+type ZapsterFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+const ZAPSTER_SEND_MESSAGE_URL = "https://api.zapsterapi.com/v1/wa/messages";
+
 export function buildZapsterSendMessageRequest(input: ChannelSendInput): ZapsterSendMessageRequest {
+  return buildZapsterSendMessageRequestInternal(input, "<redacted>");
+}
+
+export async function sendZapsterMessage(
+  input: ChannelSendInput,
+  fetcher: ZapsterFetch = fetch,
+): Promise<ChannelSendResult> {
+  if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    const request = buildZapsterSendMessageRequest(input);
+
+    return {
+      ok: true,
+      status: "stubbed",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const apiKey = input.secrets.ZAPSTER_API_KEY;
+  const instanceId = input.secrets.ZAPSTER_INSTANCE_ID;
+
+  if (!apiKey || !instanceId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret ZAPSTER_API_KEY or ZAPSTER_INSTANCE_ID is missing.",
+    };
+  }
+
+  let request: ZapsterSendMessageRequest;
+  let actualRequest: ZapsterSendMessageRequest;
+
+  try {
+    request = buildZapsterSendMessageRequest(input);
+    actualRequest = buildZapsterSendMessageRequestInternal(input, instanceId);
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(actualRequest.url, {
+      method: actualRequest.method,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (error) {
+    const errorMessage = redactString(error instanceof Error ? error.message : String(error), [apiKey, instanceId]);
+
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Zapster sendMessage request failed before a response: ${errorMessage}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const payload = await readZapsterResponseBody(response);
+  const redactedPayload = redactValue(payload, [apiKey, instanceId]);
+  const messageId = isRecord(payload)
+    ? readString(payload, "message_id") ?? readString(payload, "id")
+    : undefined;
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      retryable: response.status === 429 || response.status >= 500,
+      code: "channel_send_failed",
+      message: redactString(readZapsterErrorMessage(payload, response.status), [apiKey, instanceId]),
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        status: response.status,
+        body: redactedPayload,
+      },
+    };
+  }
+
+  if (!messageId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: "Zapster sendMessage did not return message_id or id.",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        status: response.status,
+        body: redactedPayload,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    status: "sent",
+    providerRequestId: request.idempotencyKey,
+    providerMessageId: messageId,
+    providerMetadata: {
+      method: request.method,
+      url: request.url,
+      status: response.status,
+      body: redactedPayload,
+    },
+  };
+}
+
+function buildZapsterSendMessageRequestInternal(
+  input: ChannelSendInput,
+  instanceId: string,
+): ZapsterSendMessageRequest {
   const to = input.externalIdentity.key.match(/contact:([^:]+)$/)?.[1];
 
   if (!to) {
@@ -266,18 +393,83 @@ export function buildZapsterSendMessageRequest(input: ChannelSendInput): Zapster
 
   return {
     method: "POST",
-    url: "https://api.zapster.example/messages",
+    url: ZAPSTER_SEND_MESSAGE_URL,
     body: {
-      to,
-      type: "text",
-      text: {
-        body: input.message.content,
-      },
+      recipient: to,
+      text: input.message.content,
+      instance_id: instanceId,
     },
     idempotencyKey: `whatsapp:zapster:${input.channelId}:${input.conversationId}:${redactPhone(to)}`,
   };
 }
 
+async function readZapsterResponseBody(response: Response): Promise<unknown> {
+  const text = await response.text().catch(() => "");
+
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function readZapsterErrorMessage(payload: unknown, status: number): string {
+  if (typeof payload === "string" && payload.length > 0) {
+    return payload;
+  }
+
+  if (isRecord(payload)) {
+    const message = readString(payload, "message") ?? readString(payload, "error") ?? readString(payload, "detail");
+
+    if (message) {
+      return message;
+    }
+
+    const error = readRecord(payload, "error");
+    const nestedMessage = readString(error, "message") ?? readString(error, "detail");
+
+    if (nestedMessage) {
+      return nestedMessage;
+    }
+  }
+
+  return `Zapster sendMessage returned HTTP ${status}.`;
+}
+
+function redactValue(value: unknown, secrets: string[]): unknown {
+  if (typeof value === "string") {
+    return redactString(value, secrets);
+  }
+
+  if (!isRecord(value) && !Array.isArray(value)) {
+    return value;
+  }
+
+  const serialized = redactString(JSON.stringify(value), secrets);
+
+  try {
+    return JSON.parse(serialized) as unknown;
+  } catch {
+    return serialized;
+  }
+}
+
+function redactString(value: string, secrets: string[]): string {
+  let redacted = value;
+
+  for (const secret of secrets) {
+    if (secret) {
+      redacted = redacted.split(secret).join("<redacted>");
+    }
+  }
+
+  return redacted;
+}
+
 function parseJsonObject(input: RawWebhookEvent): Record<string, unknown> {
   try {
     const parsed = JSON.parse(input.rawBody) as unknown;

package/src/runtime/channels.ts

@@ -13,6 +13,9 @@ export type ChannelDeliveryState =
   | "queued"
   | "running"
   | "agent_completed"
+  | "adapter_stubbed"
+  | "provider_request_built"
+  | "provider_sent"
   | "outbound_sent"
   | "provider_failed"
   | "synthetic_expected_failure"
@@ -89,7 +92,7 @@ export type ChannelSendResult =
       ok: true;
       providerRequestId?: string;
       providerMessageId?: string;
-      status: "sent" | "delivered";
+      status: "stubbed" | "sent" | "delivered";
       providerMetadata?: Record<string, unknown>;
     }
   | {

package/src/runtime/targets/cloudflare/build.ts

@@ -781,6 +781,7 @@ export default {
 
 function isHostedChannelWebhookPath(pathname) {
   return (
+    /^\\/channels\\/[^/]+\\/(?:website\\/agentkit|telegram\\/telegram|whatsapp\\/(?:zapster|meta))\\/webhook$/.test(pathname) ||
     /^\\/channels\\/[^/]+\\/(?:website|telegram)\\/webhook$/.test(pathname) ||
     /^\\/channels\\/[^/]+\\/whatsapp\\/(?:zapster|meta)\\/webhook$/.test(pathname)
   );

package/src/templates/skills/agentkit-channels/references/channel-buffering.md

@@ -43,6 +43,11 @@ Behavior:
 Debug:
 
 ```sh
+agentkit channels buffers list <name>
+agentkit channels buffers show <conversation-id>
+agentkit channels buffers flush <conversation-id>
+agentkit channels buffers clear <conversation-id>
+agentkit channels buffers retry <conversation-id>
 agentkit channels deliveries list <name>
 agentkit channels deliveries show <delivery-id>
 ```
@@ -54,5 +59,7 @@ buffered
 queued
 running
 agent_completed
-outbound_sent
+provider_request_built
+provider_sent
+adapter_stubbed
 ```

package/src/templates/skills/agentkit-channels/references/channel-debugging.md

@@ -9,6 +9,11 @@ agentkit channels doctor <name>
 agentkit channels test <name> --message "hello"
 agentkit channels deliveries list <name> --since 24h
 agentkit channels deliveries show <delivery-id>
+agentkit channels buffers list <name>
+agentkit channels buffers show <conversation-id>
+agentkit channels buffers flush <conversation-id>
+agentkit channels buffers clear <conversation-id>
+agentkit channels buffers retry <conversation-id>
 ```
 
 Common states:
@@ -21,7 +26,9 @@ buffered
 queued
 running
 agent_completed
-outbound_sent
+provider_request_built
+provider_sent
+adapter_stubbed
 delivered
 provider_failed
 synthetic_expected_failure
@@ -39,3 +46,5 @@ Common errors:
 - `channel_limit_exceeded`: backpressure skipped the message.
 - `synthetic_expected_failure`: a synthetic test reached AgentKit, but the provider correctly rejected a fake test recipient.
 - `buffered` delivery state: message is waiting for the channel quiet window or max wait before one coalesced agent run is queued.
+- `adapter_stubbed`: explicit dry-run mode built a provider request but did not call the provider.
+- `provider_sent`: the provider accepted the outbound send and returned a provider message ID.

package/src/templates/skills/agentkit-channels/references/whatsapp-zapster.md

@@ -29,6 +29,8 @@ Paste the stable AgentKit webhook URL into Zapster settings. If the channel decl
 
 AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`. Unsupported media should be logged as skipped/unsupported without creating an agent run.
 
+Outbound replies call `POST https://api.zapsterapi.com/v1/wa/messages` with bearer auth and a JSON body containing `recipient`, `text`, and `instance_id`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Zapster should not receive a real message.
+
 Buffer rapid WhatsApp messages:
 
 ```ts