@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.21

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

@@ -0,0 +1,121 @@
+# Connect WhatsApp Through Evolution API
+
+## Goal
+
+Connect a self-hosted Evolution API WhatsApp instance to a hosted AgentKit WhatsApp channel.
+
+## When To Use It
+
+Use this after `whatsappChannel({ name: "main-whatsapp", provider: "evolution" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit channels connect whatsapp main-whatsapp --provider evolution
+agentkit channels status main-whatsapp
+agentkit channels test main-whatsapp --message "hello"
+agentkit channels deliveries list main-whatsapp
+agentkit channels buffers list main-whatsapp
+```
+
+Required secrets:
+
+```txt
+EVOLUTION_API_BASE_URL
+EVOLUTION_API_KEY
+EVOLUTION_INSTANCE_NAME
+EVOLUTION_WEBHOOK_TOKEN
+```
+
+If WhatsApp audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+## Minimal Working Example
+
+```ts
+import { defineAgent, whatsappChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "my-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [whatsappChannel({ name: "main-whatsapp", provider: "evolution" })],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+## Setup Behavior
+
+`agentkit channels connect whatsapp main-whatsapp --provider evolution` creates or updates the hosted channel, verifies managed secrets, calls Evolution API `POST /webhook/set/{instance}`, confirms the configured webhook through `GET /webhook/find/{instance}`, then runs a synthetic inbound smoke.
+
+Expected webhook URL shape:
+
+```txt
+https://<deploy-host>/channels/main-whatsapp/whatsapp/evolution/webhook
+```
+
+AgentKit registers the webhook URL with the required token query parameter:
+
+```txt
+https://<deploy-host>/channels/main-whatsapp/whatsapp/evolution/webhook?token=<EVOLUTION_WEBHOOK_TOKEN>
+```
+
+`EVOLUTION_API_BASE_URL` must be the public HTTPS origin for the Evolution API server, for example `https://evolution.example.com`. AgentKit rejects HTTP, localhost, private-network, link-local, metadata, and credential-bearing base URLs before sending `EVOLUTION_API_KEY`.
+
+## Audio
+
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on the Evolution channel.
+
+```ts
+whatsappChannel({
+  name: "main-whatsapp",
+  provider: "evolution",
+  audio: {
+    mode: "transcribe",
+  },
+})
+```
+
+Evolution audio webhooks become normalized audio messages. The retryable channel worker downloads media through Evolution API `POST /chat/getBase64FromMediaMessage/{instance}` and sends the bytes to AgentKit's configured transcription provider.
+
+## Safety Rules
+
+- Keep phone numbers redacted in logs by default.
+- Do not store Evolution API keys or webhook tokens in `agentkit.config.ts`.
+- `EVOLUTION_WEBHOOK_TOKEN` is required because AgentKit V1 does not rely on an Evolution webhook body-signature contract.
+- AgentKit ignores `fromMe` messages to avoid reply loops.
+- Text replies call Evolution API `POST /message/sendText/{instance}` with the `apikey` header and a body containing `number` and `text`.
+- Real provider success is recorded as `provider_sent` only when Evolution returns a provider message id.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Evolution should not receive a real message. Dry-run deliveries are recorded as `adapter_stubbed`, not sent.
+
+## Verification
+
+```sh
+agentkit channels setup main-whatsapp --apply
+agentkit channels status main-whatsapp
+agentkit channels test main-whatsapp --message "hello"
+agentkit channels test-audio main-whatsapp --fixture voice-note
+agentkit channels deliveries list main-whatsapp
+agentkit channels deliveries show <delivery-id>
+```
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `EVOLUTION_WEBHOOK_TOKEN` as hosted managed secrets.
+
+`channel_signature_invalid`:
+The Evolution webhook query token does not match.
+
+`channel_provider_setup_invalid`:
+`EVOLUTION_API_BASE_URL` is not an allowed public HTTPS base URL.
+
+`channel_provider_setup_failed`:
+AgentKit could not configure or verify the Evolution webhook through `/webhook/set/{instance}` and `/webhook/find/{instance}`.
+
+`channel_audio_download_unavailable`:
+Evolution did not return base64 media data from `/chat/getBase64FromMediaMessage/{instance}`, or the audio payload did not include a provider message id.

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

@@ -0,0 +1,126 @@
+# Connect WhatsApp Through UAZAPI
+
+## Goal
+
+Connect a UAZAPI WhatsApp instance to a hosted AgentKit WhatsApp channel.
+
+## When To Use It
+
+Use this after `whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit channels connect whatsapp support-whatsapp --provider uazapi
+agentkit channels status support-whatsapp
+agentkit channels test support-whatsapp --message "hello"
+agentkit channels deliveries list support-whatsapp
+agentkit channels buffers list support-whatsapp
+```
+
+Required secrets:
+
+```txt
+UAZAPI_BASE_URL
+UAZAPI_TOKEN
+```
+
+Optional hardening secret:
+
+```txt
+UAZAPI_WEBHOOK_TOKEN
+```
+
+If WhatsApp audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+## Minimal Working Example
+
+```ts
+import { defineAgent, whatsappChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+## Setup Behavior
+
+`agentkit channels connect whatsapp support-whatsapp --provider uazapi` creates or updates the hosted channel, verifies managed secrets, calls UAZAPI `/webhook`, confirms the configured webhook is listed by UAZAPI, then runs a synthetic inbound smoke.
+
+Expected webhook URL shape:
+
+```txt
+https://<deploy-host>/channels/support-whatsapp/whatsapp/uazapi/webhook
+```
+
+If the channel declares `UAZAPI_WEBHOOK_TOKEN`, AgentKit registers the webhook URL with the token query parameter:
+
+```txt
+https://<deploy-host>/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>
+```
+
+`UAZAPI_BASE_URL` must be an HTTPS UAZAPI instance URL, for example `https://api.uazapi.com`. AgentKit rejects localhost, private-network, link-local, metadata, and credential-bearing base URLs before sending `UAZAPI_TOKEN`.
+
+## Audio
+
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on the UAZAPI channel.
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "uazapi",
+  audio: {
+    mode: "transcribe",
+  },
+})
+```
+
+UAZAPI audio webhooks become normalized audio messages. The retryable channel worker downloads media through UAZAPI `/message/download` using `return_base64: true`; AgentKit does not fetch arbitrary webhook-provided media URLs.
+
+## Safety Rules
+
+- Keep phone numbers redacted in logs by default.
+- Do not store UAZAPI tokens in `agentkit.config.ts`.
+- Use optional `UAZAPI_WEBHOOK_TOKEN` when the endpoint should require a secret query token in addition to the public route.
+- UAZAPI does not expose a documented webhook body-signature contract in AgentKit V1; treat the optional query token as the hardening layer.
+- AgentKit ignores `fromMe` and `wasSentByApi` messages to avoid reply loops.
+- Text replies call UAZAPI `POST /send/text` with the `token` header and a body containing `number`, `text`, `readchat`, `async`, `track_source`, and `track_id`.
+- Real provider success is recorded as `provider_sent` only when UAZAPI returns a provider message id.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when UAZAPI should not receive a real message. Dry-run deliveries are recorded as `adapter_stubbed`, not sent.
+
+## Verification
+
+```sh
+agentkit channels setup support-whatsapp --apply
+agentkit channels status support-whatsapp
+agentkit channels test support-whatsapp --message "hello"
+agentkit channels test-audio support-whatsapp --fixture voice-note
+agentkit channels deliveries list support-whatsapp
+agentkit channels deliveries show <delivery-id>
+```
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `UAZAPI_BASE_URL` and `UAZAPI_TOKEN` as hosted managed secrets. If the channel declares `UAZAPI_WEBHOOK_TOKEN`, set that managed secret too.
+
+`channel_signature_invalid`:
+The optional UAZAPI webhook query token does not match.
+
+`channel_provider_setup_invalid`:
+`UAZAPI_BASE_URL` is not an allowed HTTPS public base URL.
+
+`channel_provider_setup_failed`:
+AgentKit could not configure or verify the UAZAPI webhook through `/webhook`.
+
+`channel_audio_download_unavailable`:
+UAZAPI did not return base64 media data from `/message/download`, or the audio payload did not include a provider message id.

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

@@ -12,18 +12,37 @@ 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:
 
 ```txt
 ZAPSTER_API_KEY
-ZAPSTER_WEBHOOK_SECRET
+ZAPSTER_INSTANCE_ID
+ZAPSTER_WEBHOOK_ID
+```
+
+Optional hardening secret:
+
+```txt
+ZAPSTER_WEBHOOK_TOKEN
+```
+
+If WhatsApp audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually:
+
+```txt
+OPENAI_API_KEY
+```
+
+or:
+
+```txt
+GROQ_API_KEY
 ```
 
 ## Files Created Or Edited
@@ -50,22 +69,97 @@ export default defineAgent({
 });
 ```
 
+To handle clients who send several WhatsApp messages before waiting, enable channel buffering:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+## Auto Transcribe WhatsApp Audio
+
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on the Zapster channel.
+
+```ts
+import { defineAgent, whatsappChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "openai", model: "gpt-5.4-mini" },
+  instructions: "./prompts/instructions.md",
+  transcription: {
+    provider: "openai",
+    model: "gpt-4o-mini-transcribe",
+    secret: "OPENAI_API_KEY",
+    language: "pt",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    whatsappChannel({
+      name: "support-whatsapp",
+      provider: "zapster",
+      audio: {
+        mode: "transcribe",
+      },
+    }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+Processing order:
+
+1. AgentKit validates Zapster origin headers and the optional webhook token.
+2. Zapster audio payloads become normalized audio messages.
+3. AgentKit records `audio_received` and enqueues a channel job before acknowledging Zapster.
+4. The retryable channel worker downloads the media URL from a trusted Zapster HTTPS host using `ZAPSTER_API_KEY`.
+5. AgentKit sends the audio bytes to the configured transcription provider using the user's managed secret.
+6. The agent run receives a text message with the transcript.
+
+Zapster payloads must include a media download URL such as `audio.downloadUrl`, `audio.url`, `audio.mediaUrl`, or the snake_case equivalents. The URL must be HTTPS and hosted by Zapster; AgentKit rejects arbitrary webhook-provided hosts before sending `ZAPSTER_API_KEY`. If Zapster sends only a media ID without a download URL, AgentKit records `channel_audio_download_unavailable` and does not create an agent run for that audio in V1.
+
 ## Setup Behavior
 
-`agentkit channels setup support-whatsapp` prints the stable AgentKit webhook URL. Paste it into Zapster webhook settings and configure Zapster to send the same shared secret as `ZAPSTER_WEBHOOK_SECRET`.
+`agentkit channels setup support-whatsapp` prints the stable AgentKit webhook URL. Paste it into Zapster webhook settings.
 
 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/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>
 ```
 
 ## Safety Rules
 
 - Keep phone numbers redacted in logs by default.
 - Do not store Zapster API keys in `agentkit.config.ts`.
-- Inbound validation uses `X-Zapster-Webhook-Secret`.
+- Inbound validation uses Zapster's `X-Instance-ID`, `X-Webhook-ID`, `X-Message-ID`, `X-Attempt-Count`, and `User-Agent: Zapsterapi/...` headers.
+- Zapster webhook headers are origin validation, not a cryptographic body signature.
+- 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
 
@@ -74,15 +168,25 @@ 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
 
 `channel_secret_missing`:
-Set `ZAPSTER_API_KEY` and `ZAPSTER_WEBHOOK_SECRET` as hosted managed secrets.
+Set `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `ZAPSTER_WEBHOOK_ID` as hosted managed secrets. If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, set that managed secret too.
 
 `channel_signature_invalid`:
-Zapster is not sending the expected webhook secret.
+Zapster is not sending the expected instance/webhook IDs, or the optional query token does not match.
 
 `channel_unsupported_message_type` or skipped delivery:
 The inbound WhatsApp event was not supported text. Inspect the delivery record for provider metadata.
+
+`channel_audio_download_unavailable`:
+Zapster sent an audio event without a usable media download URL, or the URL was not an HTTPS Zapster media host. Configure Zapster to include a trusted Zapster media URL in webhook payloads, or add a Zapster media lookup adapter before enabling `audio.mode: "transcribe"`.
+
+`transcription_secret_missing`:
+Set `OPENAI_API_KEY`, `GROQ_API_KEY`, or the custom secret named in `transcription.secret` as a managed hosted secret.

package/docs/guides/create-agent.md

@@ -19,7 +19,6 @@ cd /tmp/agentkit-demo
 
 npx @andreprado/agentkit@alpha new demo --template blank
 cd demo
-npm install
 npm run typecheck
 npm run chat -- --message "hello"
 npm run agentkit -- conversations list
@@ -37,10 +36,22 @@ For the support template:
 ```sh
 npx @andreprado/agentkit@alpha new support-demo --template support
 cd support-demo
-npm install
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 ```
 
+## Windows PowerShell
+
+If PowerShell blocks `npm.ps1` or `npx.ps1` with `PSSecurityException`, run the same commands through the Windows command shims:
+
+```sh
+npx.cmd @andreprado/agentkit@alpha new demo --template blank
+npm.cmd run typecheck
+npm.cmd run chat -- --message "hello"
+npm.cmd run agentkit -- inspect
+```
+
+This keeps the capsule workflow the same without changing the machine-wide PowerShell execution policy.
+
 ## Files Created Or Edited
 
 Generated files:
@@ -86,7 +97,16 @@ Primary flow:
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The generated `AGENTS.md`, `AGENTKIT.md`, and `CLAUDE.md` tell the coding agent which files to edit and which verification commands to run.
+The generated `AGENTS.md`, `AGENTKIT.md`, `CLAUDE.md`, and `skills/` pack tell the coding agent which files to edit, which task skill to load, and which verification commands to run. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold, contract, and owner request. The default router is `skills/agentkit-capsule/SKILL.md`; `llms-full.txt` is reserved for complete-contract checks.
+
+After the owner gives the general idea, the coding agent should create or update the implementation contract itself:
+
+```sh
+npm run agentkit -- spec init --brief "Develop an appointment and intake agent for an ophthalmology office."
+npm run agentkit -- spec check
+```
+
+`AGENT_SPEC.md` is an internal working contract for the coding agent. It is not a form the owner must fill before work starts.
 
 Optional shortcut when copying a prompt into another coding agent:
 
@@ -137,6 +157,27 @@ Expected chat output:
 Echo: hello
 ```
 
+## Testing With A UI
+
+Local UI:
+
+```sh
+npm run dev
+```
+
+Open the printed `Chat:` URL and tell the owner the exact URL.
+
+Hosted deploy UI:
+
+```sh
+npm run agentkit -- deploy
+npm run agentkit -- chat-ui --deploy
+```
+
+Open the printed `Chat:` URL and tell the owner this local UI is connected to the hosted deploy.
+
+`test/fake` is deterministic. It validates the scaffold, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality. Before claiming real conversation behavior is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider.
+
 ## Safety Rules
 
 - Do not commit `.env`.
@@ -173,7 +214,7 @@ npm install
 npm run typecheck
 ```
 
-Make sure `tsconfig.json` has `moduleResolution: "Bundler"`.
+`agentkit new` installs dependencies by default. Run this if the scaffold was created with `--no-install`, the install failed, or `node_modules` was deleted. Make sure `tsconfig.json` has `moduleResolution: "Bundler"`.
 
 `No agentkit.config.ts found`:
 

package/docs/guides/debug-channel.md

@@ -0,0 +1,147 @@
+# Debug A Channel
+
+## Goal
+
+Diagnose website, Telegram, WhatsApp, Discord, Slack, or generic webhook channel setup, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
+
+## When To Use It
+
+Use this when a hosted channel is not responding, a provider is retrying messages, audio transcription is failing, or delivery status does not match the user's expectation.
+
+## Commands
+
+```sh
+agentkit channels list
+agentkit channels status <name>
+agentkit channels doctor <name>
+agentkit channels test <name> --message "hello"
+agentkit channels test-audio <name> --fixture voice-note
+agentkit transcribe smoke --provider groq
+agentkit channels test <name> --fixture ./fixtures/provider-event.json
+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>
+```
+
+## Files Created Or Edited
+
+Debugging should not require source edits. Use fixtures only when reproducing provider payload shape, and never commit provider secrets, full phone numbers, raw audio, or private client data.
+
+## Delivery States
+
+```txt
+received
+validated
+duplicate
+audio_received
+audio_downloaded
+transcribing
+transcribed
+buffered
+queued
+running
+agent_completed
+provider_request_built
+provider_sent
+adapter_stubbed
+delivered
+provider_failed
+failed
+dead_lettered
+skipped
+```
+
+## Minimal Working Example
+
+```sh
+agentkit channels test support-telegram --message "hello"
+agentkit channels deliveries list support-telegram --since 1h
+agentkit channels deliveries show del_123
+```
+
+Expected `show` output includes signature status, dedupe key, queue/run state, outbound provider request ID when available, and a normalized error envelope.
+
+## Safety Rules
+
+- Inspect delivery IDs, hashes, statuses, and redacted metadata rather than raw provider payloads.
+- Never paste provider secrets into fixtures or prompts.
+- Treat `adapter_stubbed` as "no outbound provider call happened", not proof that a client received a message. It can mean explicit dry-run mode or an inbound-only channel such as a generic webhook.
+- Before replaying or flushing buffered conversations, confirm the channel name and conversation ID.
+- Keep local `.env` values ignored and upload hosted production values through AgentKit secret commands.
+
+## Troubleshooting By Error Code
+
+`channel_not_found`:
+The webhook URL points to an unknown or deleted channel. Stable hosted URLs use the channel name, for example `/channels/support-whatsapp/whatsapp/zapster/webhook`; old `chn_*` URLs are accepted only for compatibility.
+
+`agentkit channels test <name>` is the official synthetic smoke. If it fails while `channels list`, `status`, or `doctor` find the channel, rerun against the current deploy state in `.agentkit/deploy.json`.
+
+`channel_disabled`:
+The channel was disabled. Re-add or recreate it.
+
+`channel_secret_missing`:
+The hosted secret metadata says a required channel secret is missing. Set it with `agentkit secret set <NAME> --from-local-env` or `agentkit secret sync --from-local`.
+
+`channel_signature_invalid`:
+Provider authenticity validation failed. Check the provider webhook secret, token, origin settings, or Discord public key.
+
+`channel_payload_invalid`:
+The provider payload is malformed or does not match the route provider.
+
+Discord endpoint validation fails in the Developer Portal:
+Confirm `DISCORD_PUBLIC_KEY` is set from the application's public key and the webhook URL is `/channels/<name>/discord/discord/webhook`. AgentKit must validate Discord's signature headers before returning the `PING` PONG.
+
+Discord bot does not answer normal server messages:
+Confirm the channel was created with `--mode bot`, `DISCORD_BOT_TOKEN` is set, Message Content Intent is enabled in the Discord Developer Portal, the app is installed into the server, and the bot has `View Channel`, `Read Message History`, and `Send Messages` permissions for the channel.
+
+`audio_received`:
+The webhook contained a supported audio message and the channel is entering the audio handling path.
+
+`audio_downloaded`:
+The retryable channel worker downloaded the provider media file into memory. The delivery metadata should include only redacted size, MIME, and provider IDs.
+
+`transcribing`:
+AgentKit is calling the configured transcription provider with the user's managed transcription secret.
+
+`transcribed`:
+Transcription succeeded and the queued agent message contains transcript text instead of raw audio.
+
+`channel_event_duplicate` or `duplicate`:
+The provider retried an already-processed event. No second agent run should be created.
+
+`buffered`:
+The message is accepted and waiting inside a per-conversation channel buffer. It should move to `queued` after the quiet window, max wait, max message count, or max character count.
+
+`adapter_stubbed`:
+The adapter completed without calling an outbound provider. This can happen in explicit dry-run mode or for an inbound-only channel such as a generic webhook.
+
+`provider_sent`:
+The provider API accepted the outbound request and returned a provider message ID.
+
+`channel_limit_exceeded`:
+Backpressure skipped the message before queueing.
+
+`channel_audio_download_unavailable`:
+The channel provider reported audio but did not include enough metadata for AgentKit to download it.
+
+`transcription_secret_missing`:
+The transcription provider secret declared in `agentkit inspect` is not set as a managed hosted secret.
+
+`transcription_audio_too_large` or `transcription_audio_too_long`:
+The audio exceeded `transcription.limits` or the channel-level `audio.limits`.
+
+`transcription_audio_format_unsupported`:
+The configured transcription provider does not accept this audio MIME type or file extension.
+
+`transcription_provider_unavailable`:
+The transcription provider returned a retryable error, usually HTTP 429 or a server-side failure.
+
+`channel_provider_unavailable`:
+The agent run or provider send path failed with a retryable provider condition.
+
+`channel_delivery_dead_lettered`:
+The queue exhausted retries. Inspect the delivery and replay manually only after fixing the cause.