@andreprado/agentkit 0.1.0-alpha.12 → 0.1.0-alpha.14

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/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
@@ -82,6 +97,7 @@ Zapster smoke requires `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `AGENTKIT_Z
 - 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,7 +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`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Zapster should not receive a real message.
+- 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
 
@@ -107,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.12",
+  "version": "0.1.0-alpha.14",
   "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/cloud-client.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -97,6 +97,7 @@ export async function readCloudAuth(): Promise<CloudAuthConfig | null> {
 export async function writeCloudAuth(config: CloudAuthConfig): Promise<void> {
   await mkdir(join(homedir(), ".agentkit"), { recursive: true });
   await writeFile(cloudAuthPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  await chmod(cloudAuthPath(), 0o600);
 }
 
 export async function clearCloudAuth(): Promise<void> {
@@ -178,13 +179,17 @@ function cloudAuthMatchesApiUrl(auth: CloudAuthConfig, apiUrl: string): boolean
 export async function cloudApiRequest(apiUrl: string, path: string, init: RequestInit): Promise<unknown> {
   const auth = await readCloudAuth();
   const headers = new Headers(init.headers);
+  const apiToken =
+    auth?.source === "file" && !cloudAuthMatchesApiUrl(auth, apiUrl)
+      ? undefined
+      : auth?.token;
 
   if (!headers.has("Content-Type") && init.body !== undefined) {
     headers.set("Content-Type", "application/json");
   }
 
-  if (auth?.token && !headers.has("Authorization")) {
-    headers.set("Authorization", `Bearer ${auth.token}`);
+  if (apiToken && !headers.has("Authorization")) {
+    headers.set("Authorization", `Bearer ${apiToken}`);
   }
 
   const response = await fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {

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

@@ -263,7 +263,7 @@ export async function sendZapsterMessage(
 
     return {
       ok: true,
-      status: "sent",
+      status: "stubbed",
       providerRequestId: request.idempotencyKey,
       providerMetadata: {
         method: request.method,
@@ -351,11 +351,27 @@ export async function sendZapsterMessage(
     };
   }
 
+  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: messageId ?? request.idempotencyKey,
-    ...(messageId ? { providerMessageId: messageId } : {}),
+    providerRequestId: request.idempotencyKey,
+    providerMessageId: messageId,
     providerMetadata: {
       method: request.method,
       url: request.url,

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/config.ts

@@ -32,6 +32,7 @@ const KNOWLEDGE_EMBEDDING_PROVIDERS = new Set<AgentKnowledgeEmbeddingProvider>([
 const CHANNEL_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
 const SECRET_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 const moduleDir = dirname(fileURLToPath(import.meta.url));
+let configImportNonce = 0;
 
 export type LoadedAgentCapsule = {
   root: string;
@@ -108,15 +109,13 @@ function resolveLocalStoragePath(root: string, config: AgentConfig): string | un
 }
 
 async function loadConfigModule(configPath: string): Promise<unknown> {
-  const configUrl = pathToFileURL(configPath);
-  configUrl.searchParams.set("t", String(Date.now()));
+  const source = await readFile(configPath, "utf8");
 
   try {
-    const module = (await import(configUrl.href)) as { default?: unknown };
-    return module.default;
+    return await importConfigSource(configPath, source);
   } catch (error) {
     if (isMissingAgentKitSelfImport(error)) {
-      return loadConfigModuleWithLocalSelfImport(configPath, error);
+      return loadConfigModuleWithLocalSelfImport(configPath, source, error);
     }
 
     throw new AgentKitError(
@@ -127,8 +126,11 @@ async function loadConfigModule(configPath: string): Promise<unknown> {
   }
 }
 
-async function loadConfigModuleWithLocalSelfImport(configPath: string, originalError: unknown): Promise<unknown> {
-  const source = await readFile(configPath, "utf8");
+async function loadConfigModuleWithLocalSelfImport(
+  configPath: string,
+  source: string,
+  originalError: unknown,
+): Promise<unknown> {
   const localAgentKitUrl = pathToFileURL(resolve(moduleDir, "../index.ts")).href;
   const patchedSource = source.replace(
     /from\s+["']@andreprado\/agentkit["']/g,
@@ -143,15 +145,20 @@ async function loadConfigModuleWithLocalSelfImport(configPath: string, originalE
     );
   }
 
+  return importConfigSource(configPath, patchedSource);
+}
+
+async function importConfigSource(configPath: string, source: string): Promise<unknown> {
+  const nonce = nextConfigImportNonce();
   const tempConfigPath = join(
     dirname(configPath),
-    `.agentkit.config.loader-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.ts`,
+    `.agentkit.config.loader-${process.pid}-${nonce}-${Math.random().toString(16).slice(2)}.ts`,
   );
 
   try {
-    await writeFile(tempConfigPath, patchedSource);
+    await writeFile(tempConfigPath, source);
     const configUrl = pathToFileURL(tempConfigPath);
-    configUrl.searchParams.set("t", String(Date.now()));
+    configUrl.searchParams.set("t", nonce);
     const module = (await import(configUrl.href)) as { default?: unknown };
     return module.default;
   } catch (error) {
@@ -165,6 +172,11 @@ async function loadConfigModuleWithLocalSelfImport(configPath: string, originalE
   }
 }
 
+function nextConfigImportNonce(): string {
+  configImportNonce += 1;
+  return `${Date.now()}-${configImportNonce}`;
+}
+
 function isMissingAgentKitSelfImport(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
   return message.includes("@andreprado/agentkit");

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.