@andreprado/agentkit 0.1.1 → 0.2.0

package/README.md

@@ -1,86 +1,17 @@
-# AgentKit
+# @andreprado/agentkit
 
-AgentKit is a CLI-first toolkit for creating, running, inspecting, and deploying Agent Capsules.
-
-## Quick Start
+Create and run local Agent Capsules with prompts, TypeScript tools, evals, SQLite storage, knowledge retrieval, and channel adapters.
 
 ```sh
-npx @andreprado/agentkit@alpha new support-agent --template support
-cd support-agent
+npx @andreprado/agentkit new my-agent --template blank
+cd my-agent
 npm run dev
 npm run chat -- --message "hello"
+npm run agentkit -- inspect
 ```
 
-For a Portuguese dental-office starter, use:
-
-```sh
-npx @andreprado/agentkit@alpha new clara-dentista --template dentista
-```
-
-`agentkit new` installs the generated capsule dependencies by default so `agentkit.config.ts` resolves `@andreprado/agentkit` immediately in editors. Use `--no-install` only for offline or scripted scaffolds where you want to run `npm install` later.
-
-Generated capsules use the built-in `test/fake` provider by default, so the first local run works without provider keys.
-
-## What To Know First
-
-```sh
-agentkit new [name] [--template blank|support|dentista] [--no-install]
-agentkit new .
-agentkit dev
-agentkit chat --message <text> [--conversation-id <id>]
-agentkit inspect
-```
-
-Run `agentkit new` without a name in an interactive terminal to be prompted for the project folder. Use `agentkit new .` to create the capsule in the current directory.
-
-Once the capsule is running:
-
-```sh
-agentkit tool <name> [--input <path-or-json>]
-agentkit knowledge add <path-or-url>
-agentkit knowledge sync
-agentkit knowledge search <query> [--top-k <number>]
-agentkit integrations status
-agentkit integrations connect composio --toolkit gmail
-agentkit spec init --brief <text>
-agentkit db migrate
-agentkit sync run
-agentkit eval run
-agentkit eval from-conversation <conversation-id>
-agentkit improve collect --deploy --since 24h
-agentkit improve evals .agentkit/improve/<run>
-agentkit replay .agentkit/improve/<run> --against local
-agentkit conversations list
-agentkit conversations trace <conversation-id>
-```
-
-Knowledge indexes local `.md`, `.txt`, and `.csv` sources into the capsule database and registers the internal `agentkit_search_knowledge` chat tool when `knowledge` is configured in `agentkit.config.ts`. `agentkit dev` and `agentkit chat` sync configured sources automatically; when embeddings are configured, local semantic search uses a libSQL vector sidecar. Hosted Cloudflare deploys package configured local Knowledge sources and sync them into the project Turso database automatically during `agentkit deploy`; when embeddings are configured, the deploy also creates and populates the hosted Turso vector index.
-
-Every chat run receives dynamic runtime date context: current ISO timestamp, local date, weekday, local date/time, and timezone. Set `timeZone` in `agentkit.config.ts` for scheduling agents so relative dates like "today" and "next Friday" resolve in the right business/user timezone.
-
-AgentKit-managed Composio is a paid hosted integration layer for per-agent connected apps. Configure it with `composioManaged({...})`, deploy with a `managed_composio` entitlement, then use `agentkit integrations connect composio --toolkit <slug>` to create hosted Connect Links. BYO Composio remains available through normal `defineTool` wrappers.
-
-## Deploy Later
-
-```sh
-agentkit login --token <token>
-agentkit deploy doctor
-agentkit skills status
-agentkit secret set OPENAI_API_KEY --from-local-env
-agentkit deploy
-agentkit deploy status
-agentkit channels test support-telegram --message "hello"
-agentkit channels connect webhook n8n-webhook
-agentkit transcribe smoke --provider groq
-agentkit chat-ui --deploy
-```
-
-Production secrets are managed secrets, not committed `.env` values.
-After upgrading AgentKit in an existing capsule, run `agentkit skills status` and `agentkit skills sync` if local agent-facing skills are stale.
-Private hosted deploys automatically store a local chat/UI deploy access token at `.agentkit/chat-access-token.json`. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy without exposing that token to browser code.
-
-The npm package contains the public CLI/runtime/client surface only. AgentKit Cloud's control-plane server, operator commands, Postgres store, and Cloudflare/Turso/R2 publisher live in the private repo workspace and are not part of the published package.
+Requires Node 24+. Capsules start with the deterministic `test/fake` provider. Choose a real provider before testing conversation quality; provider adapters use Pi. Store local credentials with `agentkit env set <NAME> --stdin` and connect external services through `defineTool`.
 
-## Full Reference
+Run `agentkit docs llms` for the docs router or `agentkit docs full` for the operating contract. Existing capsules should read `docs/guides/local-only-migration.md` when upgrading from a version with hosted features.
 
-`agentkit --help` keeps the first surface focused. Run `agentkit help commands` for the full CLI reference and `agentkit docs full` to print the path to the full agent-facing operating contract.
+AgentKit runs locally. Channel webhooks can use an authenticated HTTPS tunnel while the local process is running. No account, billing, managed hosting, or deployment service is included.

package/docs/guides/add-channel.md

@@ -2,45 +2,12 @@
 
 ## Goal
 
-Add a hosted messaging channel to an Agent Capsule, create the hosted channel resource, and verify that inbound messages become AgentKit channel deliveries without exposing secrets.
+Add a local messaging channel to an Agent Capsule, create the local channel resource, and verify that inbound messages become AgentKit channel deliveries without exposing secrets.
 
 ## When To Use It
 
 Use this when the agent should receive messages from website chat, Telegram, WhatsApp, Discord, Slack, or a generic webhook through AgentKit-owned channel infrastructure, or when an inbound channel should reply through another configured channel.
 
-## Commands
-
-```sh
-agentkit inspect
-agentkit deploy
-agentkit channels list
-agentkit channels add website website-chat
-agentkit channels add telegram support-telegram
-agentkit channels connect discord support-discord
-agentkit channels connect discord server-discord --mode bot
-agentkit channels connect slack support-slack
-agentkit channels connect webhook n8n-webhook
-agentkit channels add whatsapp support-whatsapp --provider zapster
-agentkit channels connect whatsapp support-uazapi --provider uazapi
-agentkit channels connect whatsapp main-whatsapp --provider evolution
-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>` only when the owner gives you a non-default AgentKit Cloud API URL.
-
-## Files Created Or Edited
-
-- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, `whatsappChannel`, `discordChannel`, `slackChannel`, `webhookChannel`, or `webhookOutputChannel`.
-- `.agentkit/deploy.json`: written by `agentkit deploy`; used by `agentkit channels ...`.
-- No user Turso tables: AgentKit owns channel resources, dedupe, identities, queue state, and delivery logs.
-- Website channel clients must send `AGENTKIT_WEBSITE_CHANNEL_TOKEN` as `Authorization: Bearer <token>` or `X-AgentKit-Channel-Token`.
-- Generic inbound webhook clients must send `AGENTKIT_WEBHOOK_SECRET` as `Authorization: Bearer <token>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac>`.
-- Generic outbound webhook channels send replies to an HTTPS URL stored in a managed secret such as `CRM_CALLBACK_URL`.
-
 ## Minimal Working Example
 
 ```ts
@@ -48,7 +15,7 @@ import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChan
 
 export default defineAgent({
   name: "support-agent",
-  runtime: "edge",
+  runtime: "local",
   provider: { name: "test", model: "fake" },
   instructions: "./prompts/instructions.md",
   secrets: [],
@@ -59,8 +26,7 @@ export default defineAgent({
     whatsappChannel({ name: "support-whatsapp", provider: "zapster" }),
     whatsappChannel({ name: "support-uazapi", provider: "uazapi" }),
     whatsappChannel({ name: "main-whatsapp", provider: "evolution" }),
-    discordChannel({ name: "support-discord" }),
-    discordChannel({ name: "server-discord", mode: "bot" }),
+    discordChannel({ name: "support-discord", mode: "interactions" }),
     slackChannel({ name: "support-slack" }),
     webhookChannel({ name: "n8n-webhook" }),
     webhookOutputChannel({ name: "crm-callback", urlSecret: "CRM_CALLBACK_URL" }),
@@ -94,15 +60,8 @@ Use `buffer: { mode: "off" }` or omit `buffer` to process each inbound message a
 
 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>
-```
 
-Discord supports buffering for slash-command interactions and bot-mode server messages, but it does not support `audio` in V1.
+Discord supports buffering for slash-command interactions. Bot-mode server messages require your own Gateway bridge: AgentKit does not listen to the Gateway, and inviting a bot alone will not deliver messages. `agentkit inspect` warns when bot mode is configured. See [Connect Discord](connect-discord.md). Discord does not support `audio` in V1.
 
 ## Generic Webhooks
 
@@ -114,16 +73,13 @@ webhookChannel({
 })
 ```
 
-After deploy:
+With the local process and HTTPS tunnel running:
 
-```sh
-agentkit channels connect webhook n8n-webhook
-```
 
-The hosted webhook URL is:
+The local webhook URL is:
 
 ```txt
-https://<deploy-host>/channels/n8n-webhook/webhook
+https://<tunnel-host>/channels/n8n-webhook/webhook
 ```
 
 Send canonical JSON:
@@ -141,7 +97,7 @@ Send canonical JSON:
 Authenticate with a shared secret:
 
 ```sh
-curl -X POST https://<deploy-host>/channels/n8n-webhook/webhook \
+curl -X POST https://<tunnel-host>/channels/n8n-webhook/webhook \
   -H 'content-type: application/json' \
   -H 'authorization: Bearer <AGENTKIT_WEBHOOK_SECRET>' \
   -d '{"event_id":"evt_123","external_id":"customer_123","message":"hello from n8n"}'
@@ -220,7 +176,7 @@ webhookChannel({
 })
 ```
 
-Set `CRM_CALLBACK_URL` as a managed secret. It must be a public HTTPS URL; AgentKit rejects localhost, private network, link-local, and metadata-service hosts before sending. Supported output auth modes are `none`, `bearer`, `header`, and `hmac`, and all auth values come from managed secrets.
+Set `CRM_CALLBACK_URL` in local `.env`. It must be a public HTTPS URL; AgentKit rejects localhost, private network, link-local, and metadata-service hosts before sending. Supported output auth modes are `none`, `bearer`, `header`, and `hmac`, and all auth values come from local `.env`.
 
 Outbound generic webhook requests contain the agent's final text answer:
 
@@ -238,7 +194,6 @@ Outbound generic webhook requests contain the agent's final text answer:
 }
 ```
 
-Generic output channels do not have public inbound webhook URLs. `agentkit channels test <output-name>` is unsupported because there is no inbound endpoint to smoke.
 
 ## Auto Transcribe Audio
 
@@ -247,7 +202,7 @@ Use `transcription` at the agent level and `audio.mode: "transcribe"` on each Te
 ```ts
 export default defineAgent({
   name: "support-agent",
-  runtime: "edge",
+  runtime: "local",
   provider: { name: "openai", model: "gpt-5.4-mini" },
   instructions: "./prompts/instructions.md",
   transcription: {
@@ -311,48 +266,15 @@ V1 keeps the raw audio in memory for the request path and delivery metadata only
 ## Safety Rules
 
 - Never put provider token values in `agentkit.config.ts`.
-- Keep local values in ignored `.env`; hosted production uses managed secrets with no readback.
+- Keep local values in ignored `.env`.
 - Treat channel webhook URLs as public transport endpoints. Provider validation or the AgentKit website channel token controls authenticity.
 - Keep channels separate from tools. Channels deliver user messages; tools let the agent call external systems.
 - Keep `maxMessages` and `maxChars` bounded so one burst cannot create an oversized prompt or unexpected model spend.
 - Keep `audio.limits` bounded so one voice note cannot create unexpected transcription spend.
 
-## Verification
-
-```sh
-npm run typecheck
-bun test
-agentkit inspect
-agentkit channels list
-agentkit channels test n8n-webhook --message "hello"
-agentkit channels test support-telegram --message "hello"
-agentkit channels test-audio support-telegram --fixture voice-note
-agentkit transcribe smoke --provider groq
-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`. `adapter_stubbed` means no outbound provider call was made, either because explicit dry-run mode is enabled or the channel is inbound-only.
-
-## Troubleshooting
-
-`No .agentkit/deploy.json found`:
-Run `agentkit deploy` before creating hosted channel resources.
-
-`channel_secret_missing`:
-Set the named hosted secret. Do not add production values to `.env`.
-
-`channel_signature_invalid`:
-The provider webhook secret, token, origin header, or Discord Ed25519 signature does not match the managed secret.
-
-`channel_limit_exceeded`:
-The channel daily message limit was reached. Website requests return `429`; Telegram, WhatsApp, and Discord are acknowledged and skipped to avoid provider retry storms.
 
-`transcription_secret_missing`:
-Set the managed transcription secret declared by `agentkit inspect`, for example `OPENAI_API_KEY` or `GROQ_API_KEY`.
+## Run Locally
 
-`transcription_audio_format_unsupported`:
-The channel delivered an audio format the configured transcription provider does not accept. Telegram voice notes are OGG/Opus and work with Groq in V1; OpenAI accepts MP3, MP4, MPEG, MPGA, M4A, WAV, and WEBM in the AgentKit adapter.
+Set secret values with `agentkit env set <NAME> --stdin`, run `agentkit inspect`, then `agentkit dev`. Test channel fixtures with authenticated POST requests to the local webhook route, then inspect the response and conversation trace. Configure provider webhooks manually against an HTTPS tunnel to the printed port. Only authenticated channel webhook routes accept tunnel hosts; chat, tools, files, and inspection stay loopback-only. See each provider guide for required signatures or URL secrets. There is no automatic webhook registration or Discord Gateway worker.
 
-Buffered messages stay in `buffered` delivery state until the quiet window or max wait flushes them into one queued run.
+Local buffers and duplicate tracking are in memory and best-effort. Restarting loses pending messages and deduplication state. There is no durable retry worker, channel dashboard, or manual buffer-control API.

package/docs/guides/add-knowledge.md

@@ -106,26 +106,6 @@ Tool agentkit_search_knowledge: completed
 
 The retrieved chunks are persisted as internal tool output in local SQLite for evals and inspection, but they are not shown directly to the user.
 
-## Hosted Deploy
-
-Cloudflare Knowledge deploys require AgentKit-managed Turso storage:
-
-```ts
-storage: {
-  driver: "agentkit",
-  database: {
-    driver: "turso",
-    schema: "./schema.sql",
-  },
-},
-```
-
-`agentkit deploy doctor` and `agentkit build --target cloudflare` fail with an actionable error when Knowledge is configured without Turso. The Cloudflare artifact includes the Knowledge manifest, required embedding secret names, internal Knowledge schema, local source file contents, prompt policy, and hosted `agentkit_search_knowledge` runtime.
-
-During `agentkit deploy`, AgentKit Cloud provisions or resolves the project Turso database, applies the Knowledge schema, chunks every packaged local source, creates embeddings when an embedding provider is configured, and writes sources, chunks, embedding metadata, FTS rows, and a native Turso `libsql_vector_idx` index into Turso before publishing the Worker. Removed configured sources are deleted from the hosted Knowledge tables during sync.
-
-Local `agentkit knowledge add`, `agentkit knowledge sync`, `agentkit dev`, and `agentkit chat` index configured Knowledge into the local SQLite database and local libSQL vector sidecar. Hosted deploy syncs configured local Knowledge sources automatically from the deploy artifact so embedding secrets stay server-side and private source material does not move into client code. Hosted semantic search uses Turso native vector search when embeddings are configured and falls back to stored JSON embeddings if the native vector path is unavailable.
-
 ## Safety Rules
 
 - Do not put API keys, passwords, private tokens, `.env` contents, or credential exports in Knowledge files.
@@ -141,4 +121,3 @@ Local `agentkit knowledge add`, `agentkit knowledge sync`, `agentkit dev`, and `
 - `Local Knowledge currently supports .md, .txt, and .csv files`: convert the source or add a tool for unsupported formats.
 - `Knowledge embeddings require missing secret`: set the env var named by `knowledge.embedding.secret`.
 - `PSSecurityException` on Windows PowerShell: use `npm.cmd run agentkit -- knowledge sync` or `npm.cmd run agentkit -- knowledge search "refund policy" --top-k 3`.
-- Hosted build says Turso is required: add `storage.database.driver: "turso"` before deploying Knowledge.

package/docs/guides/add-tool.md

@@ -129,16 +129,15 @@ Expected output:
 
 ## Database Tool Pattern
 
-Use this when a tool needs agent-owned tables and must work locally and after deploy through the same AgentKit database helper.
+Use this when a tool needs agent-owned tables and must work locally through the same AgentKit database helper.
 
 Recommended contract:
 
 - Put the idempotent bootstrap view of agent-owned tables in `schema.sql`.
 - For production-shaped schema evolution, add ordered `migrations/*.sql` files such as `migrations/0001_clients.sql`.
-- Keep deploy-ready capsules on `storage.driver: "agentkit"`.
+- Keep local capsules on `storage.driver: "agentkit"`.
 - Local `agentkit chat`, `agentkit tool`, `agentkit dev`, and eval runs apply ordered local migrations before `schema.sql`.
 - Use `agentkit db migrate`, `agentkit db reset --yes`, `agentkit db seed [--file seed.sql]`, and `agentkit db shell` for local database setup and inspection.
-- Hosted deploy migrates/provisions the managed database internally and applies the same `schema.sql`.
 - Tools use `ctx.db` as the canonical helper. `ctx.database` and `ctx.storage.sql` are supported aliases.
 - Use `ctx.db.batch([...])` for atomic writes. Local tools can also use `ctx.db.transaction(async (tx) => ...)`.
 - Do not import local database drivers or Node-only APIs from a tool. Use runtime services such as `ctx.db`.
@@ -151,7 +150,7 @@ import { scheduleAppointment } from "./tools/schedule-appointment";
 
 export default defineAgent({
   name: "appointments",
-  runtime: "edge",
+  runtime: "local",
   provider: {
     name: "test",
     model: "fake",
@@ -238,15 +237,12 @@ npm run agentkit -- tool schedule_appointment --input '{"clientName":"Ada Lovela
 npm run agentkit -- db shell
 ```
 
-Build/deploy:
+Verify locally:
 
 ```sh
 npm run agentkit -- inspect
-npm run agentkit -- build
-npm run agentkit -- deploy
 ```
 
-`inspect` shows the local runtime state and declared secret names. The user does not create hosted databases or buckets manually; AgentKit handles deploy infrastructure internally.
 
 `ctx.runtime` tells a tool where it is running:
 
@@ -254,7 +250,7 @@ npm run agentkit -- deploy
 ctx.runtime // { environment, invocation, target, database }
 ```
 
-Use it for diagnostics only, not for bypassing AgentKit runtime services or choosing deploy infrastructure.
+Use it for diagnostics only, not for bypassing AgentKit runtime services or opening independent database connections.
 
 ## Safety Rules
 
@@ -345,5 +341,3 @@ Tool hangs:
 Set `timeoutMs`, pass `ctx.signal` to external fetch calls, and retry.
 
 ## Backend Contracts Used
-
-Local tool calls are stored in SQLite `tool_calls`. Hosted tools later run under the managed Tool Gateway contract with scoped secrets, permission checks, timeouts, and redacted logs.

package/docs/guides/channel-security.md

@@ -1,211 +1,7 @@
 # Channel Security
 
-## Goal
+Validate the provider signature or channel secret against the raw request before normalizing it. Telegram uses its webhook secret header; Discord interactions use Ed25519 signatures; Slack uses timestamped HMAC. Zapster requires expected instance/webhook IDs plus an AgentKit URL secret; UAZAPI and Evolution require URL secrets. Generic webhooks require bearer/header authentication or an HMAC signature.
 
-Configure website, Telegram, WhatsApp, Discord, Slack, generic inbound webhook channels, and generic outbound webhook channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
+Keep tokenized URLs secret. Use HTTPS tunnels only for channel webhook paths; all other local APIs remain loopback-only. Keep provider credentials in ignored `.env`, declare their names in configuration, and never include values in prompts or fixtures. Do not weaken media download host restrictions or outbound SSRF protections.
 
-## When To Use It
-
-Use this when a coding agent adds or changes channels in an Agent Capsule, enables audio transcription, inspects deliveries, prepares a hosted deploy that receives provider webhooks, or routes replies through another channel.
-
-## Commands
-
-```sh
-agentkit inspect
-agentkit channels status <name>
-agentkit channels doctor <name>
-agentkit channels deliveries list <name> --since 24h
-agentkit channels deliveries show <delivery-id>
-```
-
-## Files Created Or Edited
-
-- `agentkit.config.ts`: channel names, provider choices, audio/buffer config, and secret names only.
-- `.env.schema`: local secret names only when the capsule needs a local provider or local smoke.
-- `.env`: local-only secret values; do not commit it.
-- Hosted managed secrets: production secret values with no readback.
-
-## Safety Rules
-
-- Public webhook URLs are not permission grants.
-- Keep provider tokens, webhook secrets, output webhook URLs, bot tokens, transcription keys, and bearer tokens out of source files.
-- Put secret names in `agentkit.config.ts`; put local values in ignored `.env`; upload production values with `agentkit secret set` or `agentkit secret sync`.
-- Do not store raw webhook bodies, raw audio, or provider secret values in tools, prompts, evals, fixtures, or delivery notes.
-- Do not expose Discord interaction tokens or bot tokens. Interaction tokens are reply tokens, not public identifiers.
-- Do not expose Slack bot tokens or signing secrets. Slack signing secrets authenticate webhook origin; Slack bot tokens authorize outbound replies.
-- Do not expose `AGENTKIT_WEBHOOK_SECRET`. Generic webhook clients must authenticate with bearer/header token auth or an HMAC signature over the exact raw body.
-- Do not put generic output webhook URLs or auth values in payloads, prompts, tools, fixtures, or `agentkit.config.ts`. Use `urlSecret` and output auth secret names only.
-- Keep generic output webhook URLs on public HTTPS origins. AgentKit rejects localhost, private network, link-local, and metadata-service hosts before sending.
-- Do not route replies to a channel name from the inbound payload. `replyTo.channel` must be static config, and `recipientFrom` may only select the recipient identifier.
-- Do not remove `EVOLUTION_WEBHOOK_TOKEN` from Evolution WhatsApp webhooks. Evolution provider docs expose webhook delivery setup but no webhook signing-secret contract, so AgentKit requires a secret token query parameter and rejects requests without it.
-- Do not remove `UAZAPI_WEBHOOK_TOKEN` or `ZAPSTER_WEBHOOK_TOKEN`. These are AgentKit-owned URL secrets, not provider-issued tokens. The adapters require them because the providers' other webhook fields do not provide a strong shared-secret signature.
-- A local HTTPS tunnel may forward only authenticated `/channels/.../webhook` routes to `agentkit dev`; the local chat, inspect, tools, files, and conversation APIs remain loopback-only.
-- Keep `EVOLUTION_API_BASE_URL` on a public HTTPS origin. AgentKit rejects localhost, private network, link-local, and metadata-service hosts for Evolution outbound and media-download requests.
-- Inspect delivery IDs, hashes, redacted metadata, and statuses instead of raw provider payloads.
-- Keep channel plumbing out of the agent's application database. The user's Turso tables are for the agent's business data.
-- Enable audio transcription only when the capsule declares a transcription provider and bounded `limits`.
-- Keep channel buffer limits bounded so bursty client messages cannot create unbounded runs or provider spend.
-
-## Minimal Working Example
-
-```ts
-telegramChannel({
-  name: "support-telegram",
-  secrets: ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"],
-});
-```
-
-With audio transcription:
-
-```ts
-export default defineAgent({
-  // ...
-  transcription: {
-    provider: "groq",
-    model: "whisper-large-v3-turbo",
-    secret: "GROQ_API_KEY",
-    limits: {
-      maxDurationSeconds: 180,
-      maxBytes: 20_000_000,
-    },
-  },
-  channels: [
-    telegramChannel({
-      name: "support-telegram",
-      audio: { mode: "transcribe" },
-    }),
-  ],
-});
-```
-
-The config contains secret names only. Hosted responses report status, not values:
-
-```txt
-TELEGRAM_BOT_TOKEN: set
-TELEGRAM_WEBHOOK_SECRET: missing
-GROQ_API_KEY: set
-```
-
-Discord slash-command mode uses a public key rather than a shared webhook secret:
-
-```ts
-discordChannel({
-  name: "support-discord",
-  secrets: ["DISCORD_PUBLIC_KEY"],
-});
-```
-
-AgentKit validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against the raw body, returns `type: 1` for Discord `PING`, and sends follow-up replies with `allowed_mentions: { parse: [] }`.
-
-Discord bot mode uses a bot token and Gateway connection:
-
-```ts
-discordChannel({
-  name: "server-discord",
-  mode: "bot",
-  secrets: ["DISCORD_BOT_TOKEN"],
-});
-```
-
-Bot mode requires Message Content Intent in the Discord Developer Portal and channel permissions for `View Channel`, `Read Message History`, and `Send Messages`. AgentKit must redact `DISCORD_BOT_TOKEN` anywhere delivery, queue, buffer, or doctor output is returned.
-
-Slack Events API uses a bot token and signing secret:
-
-```ts
-slackChannel({
-  name: "support-slack",
-  secrets: ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"],
-});
-```
-
-AgentKit validates `X-Slack-Signature` and `X-Slack-Request-Timestamp` against the raw body, rejects stale timestamps, answers Slack `url_verification` with the literal challenge, skips bot/subtype messages, and sends replies with Slack control mentions escaped.
-
-Generic webhooks use an AgentKit shared secret:
-
-```ts
-webhookChannel({
-  name: "n8n-webhook",
-  secrets: ["AGENTKIT_WEBHOOK_SECRET"],
-});
-```
-
-AgentKit validates `Authorization: Bearer <secret>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature` against the raw body before parsing business fields. Payloads must include `event_id` for replay protection. `external_id` is hashed before storage.
-
-Generic output webhooks use managed URL and auth secrets:
-
-```ts
-webhookOutputChannel({
-  name: "crm-callback",
-  urlSecret: "CRM_CALLBACK_URL",
-  auth: {
-    type: "hmac",
-    secret: "CRM_CALLBACK_SIGNING_SECRET",
-  },
-})
-```
-
-The output URL must be a public HTTPS URL stored in `CRM_CALLBACK_URL`. Supported auth modes are `none`, `bearer`, `header`, and `hmac`. For HMAC auth, AgentKit signs the exact JSON callback body and sends `sha256=<digest>` in `X-AgentKit-Webhook-Signature` unless a different `headerName` is configured.
-
-Cross-channel replies use static routing:
-
-```ts
-webhookChannel({
-  name: "lead-webhook",
-  replyTo: {
-    channel: "crm-callback",
-    recipientFrom: "crm_id",
-  },
-})
-```
-
-`replyTo.channel` must name another configured channel. `recipientFrom` is a dotted JSON path into the inbound payload and must resolve to a non-empty string, number, or boolean. It is for recipient identity only; never use inbound data to choose a callback URL, auth secret, or channel name.
-
-Evolution WhatsApp uses a self-hosted API key and an AgentKit webhook token:
-
-```ts
-whatsappChannel({
-  name: "support-whatsapp",
-  provider: "evolution",
-  secrets: [
-    "EVOLUTION_API_BASE_URL",
-    "EVOLUTION_API_KEY",
-    "EVOLUTION_INSTANCE_NAME",
-    "EVOLUTION_WEBHOOK_TOKEN",
-  ],
-});
-```
-
-AgentKit configures Evolution's webhook URL with `?token=<EVOLUTION_WEBHOOK_TOKEN>`, validates the token on ingress, redacts Evolution secret values, and rejects unsafe Evolution API base URLs before sending messages or downloading audio media.
-
-## Verification
-
-```sh
-npm run agentkit -- inspect
-npm run agentkit -- deploy doctor
-npm run agentkit -- channels status <name>
-npm run agentkit -- channels doctor <name>
-```
-
-For a synthetic channel smoke after deploy:
-
-```sh
-npm run agentkit -- channels test <name> --message "hello"
-npm run agentkit -- channels deliveries list <name> --since 1h
-```
-
-## Troubleshooting
-
-Secret value appears in output:
-Stop and remove the value from source, fixtures, prompts, evals, and delivery notes. Hosted delivery APIs must not return secret values.
-
-Phone number appears in delivery logs:
-Use the redacted delivery metadata and avoid pasting full phone numbers into committed fixtures.
-
-`channel_secret_missing`:
-Set the named hosted secret with `agentkit secret set <NAME> --from-local-env` or `agentkit secret sync --from-local`.
-
-`channel_signature_invalid`:
-Check that the provider webhook secret/token configured in the provider dashboard matches the hosted secret name declared by the channel. For Discord slash-command mode, check that `DISCORD_PUBLIC_KEY` matches the application's public key. For Discord bot mode, check that `DISCORD_BOT_TOKEN` is set and Message Content Intent is enabled.
-
-Raw audio appears in files or logs:
-Remove it. AgentKit may pass transcript text into the normalized agent message after successful transcription, but raw audio belongs outside committed capsule files.
+Use redacted delivery metadata and local traces for diagnostics. Set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` for tests that must not contact a real message recipient. Synthetic tests must not be presented as proof of successful provider delivery.