@andreprado/agentkit 0.1.1 → 0.2.0

package/docs/guides/connect-discord.md

@@ -1,178 +1,13 @@
-# Connect Discord
+# Connect Discord Locally
 
-## Goal
+Add `discordChannel({ name: "support-discord", mode: "interactions" })` to `channels` with `runtime: "local"`. Save `DISCORD_PUBLIC_KEY` in ignored `.env`.
 
-Connect Discord to a hosted AgentKit channel. Discord has two supported modes:
+Set the Discord application's Interactions Endpoint URL to `https://<tunnel-host>/channels/support-discord/discord/discord/webhook`. Register a command with a string option such as `message`. AgentKit validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against the raw body, responds to signed PING, and returns the agent reply inline with mentions disabled.
 
-- `interactions`: slash commands through Discord's Interactions Endpoint URL.
-- `bot`: normal server messages through a Discord Bot user connected to the Gateway.
+Slow provider responses may exceed Discord's interaction deadline; the local runtime has no deferred-response worker. The `bot` adapter accepts forwarded message events with `DISCORD_BOT_TOKEN`, but AgentKit does not connect to the Gateway. A bot config alone cannot receive server messages; use interactions or provide your own bridge. Discord audio is unsupported.
 
-Use `bot` mode when the agent should answer messages without a slash command.
+`agentkit inspect` reports `discord_gateway_bridge_required` for each bot-mode channel. Its adapter status remains `needs_setup` because AgentKit cannot verify an external bridge's connectivity; having a bot token does not establish a Gateway connection.
 
-## Commands
+Run `agentkit inspect`, `agentkit channels list`, and `agentkit dev`. Configure the provider webhook manually using an HTTPS tunnel to the printed port. Only authenticated webhook routes accept tunnel hosts; the dev UI and other APIs stay loopback-only. Keep the local process running and update registration if the tunnel hostname changes.
 
-Slash-command mode:
-
-```sh
-agentkit deploy
-agentkit secret set DISCORD_PUBLIC_KEY --stdin
-agentkit channels connect discord support-discord
-agentkit channels test support-discord --message "hello"
-agentkit channels deliveries list support-discord
-```
-
-Bot/server-message mode:
-
-```sh
-agentkit deploy
-agentkit secret set DISCORD_BOT_TOKEN --stdin
-agentkit channels connect discord server-discord --mode bot
-agentkit channels test server-discord --message "hello"
-agentkit channels deliveries list server-discord
-```
-
-## Minimal Config
-
-Slash commands:
-
-```ts
-discordChannel({ name: "support-discord" })
-```
-
-Normal server messages:
-
-```ts
-discordChannel({
-  name: "server-discord",
-  mode: "bot",
-})
-```
-
-Full example:
-
-```ts
-import { defineAgent, discordChannel } from "@andreprado/agentkit";
-
-export default defineAgent({
-  name: "support-agent",
-  runtime: "edge",
-  provider: { name: "test", model: "fake" },
-  instructions: "./prompts/instructions.md",
-  secrets: [],
-  tools: [],
-  channels: [
-    discordChannel({
-      name: "server-discord",
-      mode: "bot",
-      buffer: {
-        mode: "debounce",
-        quietWindowMs: 1500,
-        maxWaitMs: 8000,
-        maxMessages: 20,
-        maxChars: 8000,
-      },
-    }),
-  ],
-  access: { mode: "public" },
-  storage: { driver: "agentkit" },
-});
-```
-
-Discord audio transcription is not supported in V1. Do not add `audio` to a Discord channel.
-
-## Slash Command Setup
-
-Use this when users should run `/ask message:<text>`.
-
-Required secret:
-
-```txt
-DISCORD_PUBLIC_KEY
-```
-
-`agentkit channels connect discord support-discord` creates or refreshes the hosted channel, validates the public key, runs an AgentKit synthetic smoke, and prints the human setup step.
-
-Expected webhook URL:
-
-```txt
-https://<deploy-host>/channels/support-discord/discord/discord/webhook
-```
-
-In the Discord Developer Portal:
-
-1. Open the application.
-2. Copy the application's public key into the hosted secret named `DISCORD_PUBLIC_KEY`.
-3. Paste the AgentKit webhook URL into `Interactions Endpoint URL`.
-4. Register a slash command with a string option named `message`, `text`, `prompt`, `question`, `query`, or `input`.
-
-AgentKit answers Discord's `PING` handshake with `{ "type": 1 }`. Normal command webhooks are acknowledged with a deferred response and the retryable channel worker sends the final answer as an interaction follow-up.
-
-## Bot Setup
-
-Use this when the agent should behave like a server member and answer normal messages.
-
-Required secret:
-
-```txt
-DISCORD_BOT_TOKEN
-```
-
-`agentkit channels connect discord server-discord --mode bot` creates or refreshes the hosted channel, validates the bot token secret is present, runs an AgentKit synthetic Gateway smoke, and prints the human setup step.
-
-In the Discord Developer Portal:
-
-1. Create or open the Discord application.
-2. Open the Bot page.
-3. Reset/copy the bot token and save it as hosted secret `DISCORD_BOT_TOKEN`.
-4. Enable Message Content Intent on the Bot page.
-5. Install the app into the server with bot permissions.
-6. Grant the bot `View Channel`, `Read Message History`, and `Send Messages` in the channels it should answer.
-
-Hosted AgentKit runs a Discord Gateway worker for bot-mode channels. Discord sends `MESSAGE_CREATE` events, AgentKit ignores messages authored by bots, maps each human message to a channel conversation, runs the agent, and replies in the same Discord channel with `allowed_mentions: { parse: [] }`.
-
-For server hygiene, install or grant the bot only in channels where it should answer. Bot mode processes every readable non-bot text message the Gateway sends for that bot.
-
-## Safety Rules
-
-- Keep `DISCORD_PUBLIC_KEY` and `DISCORD_BOT_TOKEN` as managed hosted secrets; do not put values in prompts, fixtures, or source files.
-- Discord interaction tokens and bot tokens must never appear in delivery, queue, buffer, or doctor API responses.
-- Slash-command validation uses `X-Signature-Ed25519` and `X-Signature-Timestamp` against the exact raw request body.
-- Bot mode requires Discord Message Content Intent; without it, Discord sends empty message content and AgentKit skips the event.
-- Outbound Discord sends use `allowed_mentions: { parse: [] }` so agent text cannot accidentally ping users or roles.
-- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Discord should not receive a real reply. Dry-run deliveries are recorded as `adapter_stubbed`.
-
-## Verification
-
-```sh
-agentkit channels status server-discord
-agentkit channels test server-discord --message "hello"
-agentkit channels deliveries list server-discord
-agentkit channels deliveries show <delivery-id>
-agentkit channels buffers list server-discord
-```
-
-Expected bot-mode flow:
-
-1. A user sends a normal message in a Discord server channel where the bot has access.
-2. Discord sends `MESSAGE_CREATE` over the Gateway.
-3. AgentKit records an inbound delivery and enqueues the channel job.
-4. The channel queue runs the agent.
-5. AgentKit sends a bot message through `/channels/<channel_id>/messages`.
-6. Delivery status becomes `provider_sent` for a real provider send or `adapter_stubbed` in dry-run mode.
-
-## Troubleshooting
-
-`channel_secret_missing`:
-Set `DISCORD_PUBLIC_KEY` for slash-command mode or `DISCORD_BOT_TOKEN` for bot mode as a hosted managed secret.
-
-Bot does not answer normal messages:
-Confirm the channel was created with `--mode bot`, `DISCORD_BOT_TOKEN` is set, Message Content Intent is enabled in the Discord Developer Portal, and the bot has channel permissions to view, read history, and send messages.
-
-Bot answers nothing and delivery events show empty content:
-Discord Message Content Intent is missing, disabled, or not approved for the application.
-
-Discord Developer Portal rejects the slash-command endpoint:
-Confirm the deployed interaction channel is online, `DISCORD_PUBLIC_KEY` matches the application's public key, and the endpoint returns `{ "type": 1 }` for Discord's signed `PING` request.
-
-No answer appears after a queued delivery:
-Run `agentkit channels deliveries list <name>`, inspect the inbound delivery, and drain/check the channel queue.
+Test with a correctly authenticated fixture and inspect the response, then use `agentkit conversations trace <id>`. A synthetic test does not prove real provider delivery. Use `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` when a test must not send to real recipients. Local buffering is best-effort and in-memory; no durable retry worker is included.

package/docs/guides/connect-slack.md

@@ -1,126 +1,11 @@
-# Connect Slack
+# Connect Slack Locally
 
-## Goal
+Add `slackChannel({ name: "support-slack" })` to `channels` with `runtime: "local"`. Set `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` in ignored `.env`.
 
-Connect Slack to a hosted AgentKit channel through Slack Events API.
+Configure Slack Event Subscriptions with `https://<tunnel-host>/channels/support-slack/slack/slack/webhook`. Install the app with `app_mentions:read`, `im:history`, and `chat:write`, then subscribe to `app_mention` and `message.im`. AgentKit validates the raw-body signature and timestamp before answering url_verification or handling an event.
 
-V1 supports:
+Bot/subtype messages are ignored to avoid loops. Replies use chat.postMessage with mention expansion and unfurls disabled. Socket Mode, all-channel listening, file events, and Slack audio are unsupported. Processing runs in the local webhook handler; slow responses can cause provider retries.
 
-- `app_mention` events in channels.
-- `message.im` direct messages.
-- Replies through `chat.postMessage`.
+Run `agentkit inspect`, `agentkit channels list`, and `agentkit dev`. Configure the provider webhook manually using an HTTPS tunnel to the printed port. Only authenticated webhook routes accept tunnel hosts; the dev UI and other APIs stay loopback-only. Keep the local process running and update registration if the tunnel hostname changes.
 
-Slack Socket Mode, file events, audio transcription, app-management automation, and all-channel message listening are not supported in V1.
-
-## Commands
-
-```sh
-agentkit deploy
-agentkit secret set SLACK_BOT_TOKEN --stdin
-agentkit secret set SLACK_SIGNING_SECRET --stdin
-agentkit channels connect slack support-slack
-agentkit channels test support-slack --message "hello"
-agentkit channels deliveries list support-slack
-```
-
-## Minimal Config
-
-```ts
-import { defineAgent, slackChannel } from "@andreprado/agentkit";
-
-export default defineAgent({
-  name: "support-agent",
-  runtime: "edge",
-  provider: { name: "test", model: "fake" },
-  instructions: "./prompts/instructions.md",
-  secrets: [],
-  tools: [],
-  channels: [slackChannel({ name: "support-slack" })],
-  access: { mode: "public" },
-  storage: { driver: "agentkit" },
-});
-```
-
-## Slack App Setup
-
-Required hosted secrets:
-
-```txt
-SLACK_BOT_TOKEN
-SLACK_SIGNING_SECRET
-```
-
-Expected webhook URL:
-
-```txt
-https://<deploy-host>/channels/support-slack/slack/slack/webhook
-```
-
-In Slack app configuration:
-
-1. Open **Basic Information** and copy the Signing Secret into hosted secret `SLACK_SIGNING_SECRET`.
-2. Open **OAuth & Permissions** and add bot scopes:
-   - `app_mentions:read`
-   - `im:history`
-   - `chat:write`
-3. Install or reinstall the app to the workspace.
-4. Copy the Bot User OAuth Token into hosted secret `SLACK_BOT_TOKEN`.
-5. Open **Event Subscriptions**.
-6. Enable events and paste the AgentKit webhook URL as the Request URL.
-7. Subscribe to bot events:
-   - `app_mention`
-   - `message.im`
-
-AgentKit answers Slack `url_verification` challenges with the literal challenge string after signature validation.
-
-## Runtime Behavior
-
-Slack signs each request with `X-Slack-Signature` and `X-Slack-Request-Timestamp`. AgentKit verifies the signature against the raw body and rejects stale timestamps before normalizing events.
-
-For channel mentions, AgentKit maps the conversation to the Slack thread and replies in that thread. For direct messages, AgentKit maps the conversation to the Slack DM channel and user.
-
-AgentKit skips Slack bot/subtype messages to avoid reply loops. Outbound Slack delivery uses `chat.postMessage` with `parse: "none"`, disabled link-name expansion, disabled unfurls, and escaped Slack control mentions.
-
-## Safety Rules
-
-- Keep `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` as managed hosted secrets; do not put values in prompts, fixtures, evals, or source files.
-- Do not configure `audio` on `slackChannel`; Slack audio is not supported in V1.
-- Keep bot scopes narrow. V1 does not require broad channel-history scopes for all-channel listening.
-- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Slack should not receive a real reply.
-- Delivery logs return hashes and redacted metadata, never raw Slack request bodies or token values.
-
-## Verification
-
-```sh
-agentkit channels status support-slack
-agentkit channels test support-slack --message "hello"
-agentkit channels deliveries list support-slack
-agentkit channels deliveries show <delivery-id>
-agentkit channels buffers list support-slack
-```
-
-Expected flow:
-
-1. A user mentions the Slack app or sends it a direct message.
-2. Slack sends a signed Events API request.
-3. AgentKit records an inbound delivery and enqueues the channel job.
-4. The channel queue runs the agent.
-5. AgentKit sends a Slack reply through `chat.postMessage`.
-6. Delivery status becomes `provider_sent` for a real provider send or `adapter_stubbed` in dry-run mode.
-
-## Troubleshooting
-
-`channel_secret_missing`:
-Set `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` as hosted managed secrets.
-
-Slack rejects the Request URL:
-Confirm the deployed channel is online, `SLACK_SIGNING_SECRET` matches the Slack app, and the endpoint can answer Slack's signed `url_verification` challenge.
-
-No channel mention arrives:
-Confirm Event Subscriptions includes `app_mention`, the app is installed in the workspace, and the app has access to the channel where it is mentioned.
-
-No direct message arrives:
-Confirm Event Subscriptions includes `message.im` and the app has `im:history`.
-
-No answer appears after a queued delivery:
-Run `agentkit channels deliveries list support-slack`, inspect the inbound delivery, and drain/check the channel queue.
+Test with a correctly authenticated fixture and inspect the response, then use `agentkit conversations trace <id>`. A synthetic test does not prove real provider delivery. Use `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` when a test must not send to real recipients. Local buffering is best-effort and in-memory; no durable retry worker is included.

package/docs/guides/connect-telegram.md

@@ -1,170 +1,11 @@
-# Connect Telegram
+# Connect Telegram Locally
 
-## Goal
+Add `telegramChannel({ name: "support-telegram" })` to `channels` in a capsule with `runtime: "local"`. Set `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET` in ignored `.env` through `agentkit env set <NAME> --stdin`.
 
-Connect a Telegram bot to a hosted AgentKit channel with a stable AgentKit webhook URL.
+Register `https://<tunnel-host>/channels/support-telegram/telegram/telegram/webhook` with Telegram setWebhook. Set `secret_token` to `TELEGRAM_WEBHOOK_SECRET` and `allowed_updates` to `["message"]`. AgentKit validates `X-Telegram-Bot-Api-Secret-Token` before processing. It does not register the webhook automatically.
 
-## When To Use It
+For audio, set top-level `transcription` and `audio: { mode: "transcribe" }` on the channel. Telegram voice notes use OGG/Opus; the current Groq adapter accepts that format. Set its declared secret (usually `GROQ_API_KEY`). AgentKit uses Telegram getFile to download media and transcribes it locally through the chosen provider. Never log a bot-token media URL.
 
-Use this after `telegramChannel({ name: "support-telegram" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+Run `agentkit inspect`, `agentkit channels list`, and `agentkit dev`. Configure the provider webhook manually using an HTTPS tunnel to the printed port. Only authenticated webhook routes accept tunnel hosts; the dev UI and other APIs stay loopback-only. Keep the local process running and update registration if the tunnel hostname changes.
 
-## Commands
-
-```sh
-agentkit deploy
-agentkit channels add telegram support-telegram
-agentkit channels setup support-telegram
-agentkit channels setup support-telegram --apply
-agentkit channels status support-telegram
-agentkit channels test support-telegram --message "hello"
-agentkit channels deliveries list support-telegram
-```
-
-Required secrets:
-
-```txt
-TELEGRAM_BOT_TOKEN
-TELEGRAM_WEBHOOK_SECRET
-```
-
-If Telegram audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually:
-
-```txt
-GROQ_API_KEY
-```
-
-## Files Created Or Edited
-
-- `agentkit.config.ts`: `telegramChannel({ name: "support-telegram" })`.
-- `.agentkit/deploy.json`: deploy state for resolving the hosted deploy.
-- No local webhook server files.
-
-## Minimal Working Example
-
-```ts
-import { defineAgent, telegramChannel } from "@andreprado/agentkit";
-
-export default defineAgent({
-  name: "support-agent",
-  runtime: "edge",
-  provider: { name: "test", model: "fake" },
-  instructions: "./prompts/instructions.md",
-  secrets: [],
-  tools: [],
-  channels: [telegramChannel({ name: "support-telegram" })],
-  access: { mode: "public" },
-  storage: { driver: "agentkit" },
-});
-```
-
-To answer once after a burst of Telegram messages, enable channel buffering:
-
-```ts
-telegramChannel({
-  name: "support-telegram",
-  buffer: {
-    mode: "debounce",
-    quietWindowMs: 1500,
-    maxWaitMs: 8000,
-    maxMessages: 20,
-    maxChars: 8000,
-  },
-})
-```
-
-## Auto Transcribe Telegram Audio
-
-Telegram voice notes arrive as OGG/Opus. In V1, use Groq for the most obvious Telegram voice-note path because the AgentKit Groq adapter accepts `audio/ogg`.
-
-```ts
-import { defineAgent, telegramChannel } 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: "groq",
-    model: "whisper-large-v3-turbo",
-    secret: "GROQ_API_KEY",
-    language: "pt",
-    limits: {
-      maxDurationSeconds: 180,
-      maxBytes: 20_000_000,
-    },
-  },
-  channels: [
-    telegramChannel({
-      name: "support-telegram",
-      audio: {
-        mode: "transcribe",
-      },
-    }),
-  ],
-  access: { mode: "public" },
-  storage: { driver: "agentkit" },
-});
-```
-
-Processing order:
-
-1. AgentKit validates `X-Telegram-Bot-Api-Secret-Token`.
-2. Telegram `voice` or `audio` payloads become normalized audio messages.
-3. AgentKit records `audio_received` and enqueues a channel job before acknowledging Telegram.
-4. The retryable channel worker calls Telegram `getFile`, downloads the file with `TELEGRAM_BOT_TOKEN`, and does not log the token.
-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.
-
-OpenAI transcription can be used for Telegram files that arrive as MP3, MP4, MPEG, MPGA, M4A, WAV, or WEBM. Telegram voice notes are usually OGG/Opus, so they should use Groq in V1 unless the provider payload is converted before it reaches AgentKit.
-
-## Setup Behavior
-
-`agentkit channels setup support-telegram` is read-only and prints the webhook URL.
-
-`agentkit channels setup support-telegram --apply` calls Telegram `setWebhook` with:
-
-- `url`: the AgentKit webhook URL;
-- `secret_token`: `TELEGRAM_WEBHOOK_SECRET`;
-- `allowed_updates`: `["message"]`.
-
-Against AgentKit Cloud, `--apply` runs through the Cloud API and uses managed hosted secrets. The legacy local fallback only uses `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET` from the shell when the Cloud API does not expose channel setup.
-
-## Safety Rules
-
-- Use `--apply` only when real Telegram secrets are present.
-- Do not paste the bot token into code, docs, test fixtures, or delivery logs.
-- Telegram webhook validation uses `X-Telegram-Bot-Api-Secret-Token`.
-
-## Verification
-
-```sh
-agentkit channels status support-telegram
-agentkit channels test support-telegram --message "hello"
-agentkit channels test-audio support-telegram --fixture voice-note
-agentkit transcribe smoke --provider groq
-agentkit channels deliveries show <delivery-id>
-```
-
-Expected webhook URL shape:
-
-```txt
-https://<deploy-host>/channels/support-telegram/telegram/telegram/webhook
-```
-
-## Troubleshooting
-
-`TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET must be set`:
-Set both secrets before using `--apply`.
-
-`channel_signature_invalid`:
-The incoming Telegram secret token does not match `TELEGRAM_WEBHOOK_SECRET`.
-
-`channel_payload_invalid`:
-The update is malformed or is not a supported private text message.
-
-`transcription_secret_missing`:
-Set `GROQ_API_KEY` or the custom secret named in `transcription.secret` as a managed hosted secret.
-
-`transcription_audio_format_unsupported`:
-The configured transcription provider does not accept the Telegram file format. Use Groq for OGG/Opus voice notes in V1. `agentkit inspect` warns when a Telegram channel uses `audio.mode: "transcribe"` with OpenAI transcription.
+Test with a correctly authenticated fixture and inspect the response, then use `agentkit conversations trace <id>`. A synthetic test does not prove real provider delivery. Use `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` when a test must not send to real recipients. Local buffering is best-effort and in-memory; no durable retry worker is included.

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

@@ -1,121 +1,11 @@
-# Connect WhatsApp Through Evolution API
+# Connect WhatsApp Through Evolution Locally
 
-## Goal
+Add `whatsappChannel({ name: "main-whatsapp", provider: "evolution" })` to `channels` with `runtime: "local"`. Set `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `EVOLUTION_WEBHOOK_TOKEN` in ignored `.env`.
 
-Connect a self-hosted Evolution API WhatsApp instance to a hosted AgentKit WhatsApp channel.
+Register `https://<tunnel-host>/channels/main-whatsapp/whatsapp/evolution/webhook?token=<EVOLUTION_WEBHOOK_TOKEN>` with Evolution. Generate the webhook token yourself; keep the complete tokenized URL secret. The API base URL must be public HTTPS; private-network and credential-bearing URLs are rejected before forwarding credentials.
 
-## When To Use It
+AgentKit ignores fromMe messages, normalizes inbound text/audio, and sends replies through `/message/sendText/{instance}`. Audio transcription requires top-level `transcription` and channel `audio: { mode: "transcribe" }`; media is downloaded through `/chat/getBase64FromMediaMessage/{instance}`. A missing provider message id or missing base64 media produces an audio download error.
 
-Use this after `whatsappChannel({ name: "main-whatsapp", provider: "evolution" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+Run `agentkit inspect`, `agentkit channels list`, and `agentkit dev`. Configure the provider webhook manually using an HTTPS tunnel to the printed port. Only authenticated webhook routes accept tunnel hosts; the dev UI and other APIs stay loopback-only. Keep the local process running and update registration if the tunnel hostname changes.
 
-## 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.
+Test with a correctly authenticated fixture and inspect the response, then use `agentkit conversations trace <id>`. A synthetic test does not prove real provider delivery. Use `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` when a test must not send to real recipients. Local buffering is best-effort and in-memory; no durable retry worker is included.