@andreprado/agentkit 0.1.0-alpha.20 → 0.1.0-alpha.22

package/README.md

@@ -67,6 +67,7 @@ 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
 ```

package/docs/guides/add-channel.md

@@ -6,7 +6,7 @@ Add a hosted messaging channel to an Agent Capsule, create the hosted channel re
 
 ## When To Use It
 
-Use this when the agent should receive messages from website chat, Telegram, WhatsApp, or Discord through AgentKit-owned channel infrastructure.
+Use this when the agent should receive messages from website chat, Telegram, WhatsApp, Discord, Slack, or a generic webhook through AgentKit-owned channel infrastructure.
 
 ## Commands
 
@@ -19,7 +19,10 @@ 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"
@@ -31,15 +34,16 @@ Use `--api <url>` only when the owner gives you a non-default AgentKit Cloud API
 
 ## Files Created Or Edited
 
-- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, `whatsappChannel`, `discordChannel`, or `slackChannel`.
+- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, `whatsappChannel`, `discordChannel`, `slackChannel`, or `webhookChannel`.
 - `.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 webhook clients must send `AGENTKIT_WEBHOOK_SECRET` as `Authorization: Bearer <token>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac>`.
 
 ## Minimal Working Example
 
 ```ts
-import { defineAgent, discordChannel, slackChannel, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -52,9 +56,12 @@ export default defineAgent({
     websiteChannel({ name: "website-chat" }),
     telegramChannel({ name: "support-telegram" }),
     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" }),
     slackChannel({ name: "support-slack" }),
+    webhookChannel({ name: "n8n-webhook" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -95,6 +102,57 @@ 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.
 
+## Generic Webhooks
+
+Use `webhookChannel` when n8n, Make, Zapier, Pipedream, or a custom server should push a text event into the agent.
+
+```ts
+webhookChannel({
+  name: "n8n-webhook",
+})
+```
+
+After deploy:
+
+```sh
+agentkit channels connect webhook n8n-webhook
+```
+
+The hosted webhook URL is:
+
+```txt
+https://<deploy-host>/channels/n8n-webhook/webhook
+```
+
+Send canonical JSON:
+
+```json
+{
+  "event_id": "evt_123",
+  "external_id": "customer_123",
+  "message": "hello from n8n"
+}
+```
+
+`event_id` is required for replay protection. `external_id` is optional but recommended; AgentKit hashes it before storing the channel identity and uses it to continue the same conversation. If `external_id` is omitted, the event id becomes the conversation identity and each event is treated as its own conversation.
+
+Authenticate with a shared secret:
+
+```sh
+curl -X POST https://<deploy-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"}'
+```
+
+For HMAC auth, compute `HMAC-SHA256(raw JSON body, AGENTKIT_WEBHOOK_SECRET)` and send:
+
+```txt
+X-AgentKit-Webhook-Signature: sha256=<hex digest>
+```
+
+Generic webhooks are inbound-only in V1. The agent run is queued and delivery logs show the result; AgentKit does not call back into n8n unless the agent has a separate tool that does so.
+
 ## Auto Transcribe Audio
 
 Use `transcription` at the agent level and `audio.mode: "transcribe"` on each Telegram or WhatsApp channel that should accept voice notes or audio files.
@@ -125,6 +183,16 @@ export default defineAgent({
       provider: "zapster",
       audio: { mode: "transcribe" },
     }),
+    whatsappChannel({
+      name: "support-uazapi",
+      provider: "uazapi",
+      audio: { mode: "transcribe" },
+    }),
+    whatsappChannel({
+      name: "main-whatsapp",
+      provider: "evolution",
+      audio: { mode: "transcribe" },
+    }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -149,6 +217,8 @@ Processing order:
 5. The transcription adapter sends the file to the configured transcription provider.
 6. The agent receives a text message containing the transcript.
 
+Zapster audio downloads from trusted HTTPS Zapster media URLs. UAZAPI audio downloads through UAZAPI `/message/download` with base64 return enabled. Evolution audio downloads through Evolution API `/chat/getBase64FromMediaMessage/{instance}` with base64 return enabled. AgentKit does not fetch arbitrary UAZAPI or Evolution webhook media hosts.
+
 V1 keeps the raw audio in memory for the request path and delivery metadata only records redacted status/error fields. `rawAudioTtlSeconds` is part of the manifest contract for future object-storage retention, but V1 does not persist raw audio by default.
 
 ## Safety Rules
@@ -167,6 +237,7 @@ 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
@@ -175,7 +246,7 @@ 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.
+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
 

package/docs/guides/add-managed-composio.md

@@ -79,7 +79,7 @@ Expected readiness:
 
 ## Connect Apps
 
-After deploy, create a hosted Composio Connect Link:
+The Composio connect link is deploy-scoped, so declare `composioManaged(...)` first, deploy, then connect. After deploy, create a hosted Composio Connect Link:
 
 ```sh
 agentkit integrations connect composio --toolkit gmail
@@ -90,6 +90,8 @@ AgentKit prints a URL. Send that URL to the person who owns the app account.
 
 If the deploy has only one toolkit, `--toolkit` can be omitted.
 
+`agentkit deploy` prints the recommended `integrations connect composio --toolkit <slug>` command for each configured toolkit in its production handoff.
+
 ## Calendar Defaults
 
 For Google Calendar agents, include read and write actions together. Do not expose only `GOOGLECALENDAR_CREATE_EVENT`; users naturally ask to see availability before booking.

package/docs/guides/add-tool.md

@@ -112,6 +112,8 @@ Direct tool test:
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 ```
 
+When the tool touches live data, writes externally, or enforces business rules, also add deterministic checks. Use fixtures, eval-safe branches, seed data, or direct tool inputs for success and failure paths such as missing confirmation, validation errors, provider 429s/timeouts, unavailable records, and privacy/no-leak behavior. Add an eval when the agent should call the tool with specific inputs or refuse to call it until required intake or confirmation is complete.
+
 Expected output:
 
 ```json
@@ -129,9 +131,10 @@ Use this when a tool needs agent-owned tables and must work locally and after de
 
 Recommended contract:
 
-- Put all agent-owned tables in `schema.sql`.
+- 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"`.
-- Local `agentkit chat`, `agentkit tool`, `agentkit dev`, and eval runs apply `schema.sql` to local development storage.
+- 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.
@@ -176,7 +179,7 @@ CREATE TABLE IF NOT EXISTS appointments (
 );
 ```
 
-`schema.sql` is an idempotent bootstrap file in v1. Prefer `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive `ALTER TABLE` statements. AgentKit does not run destructive schema changes or ordered `migrations/*.sql` automatically yet.
+`schema.sql` is an idempotent bootstrap file. Prefer `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive `ALTER TABLE` statements. Use ordered `migrations/*.sql` for production-shaped schema evolution; `agentkit db migrate` applies unapplied local migrations before `schema.sql`.
 
 `tools/schedule-appointment.ts`:
 

package/docs/guides/channel-security.md

@@ -2,7 +2,7 @@
 
 ## Goal
 
-Configure website, Telegram, WhatsApp, Discord, and Slack channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
+Configure website, Telegram, WhatsApp, Discord, Slack, and generic webhook channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
 
 ## When To Use It
 
@@ -33,6 +33,9 @@ agentkit channels deliveries show <delivery-id>
 - 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 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.
+- 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`.
@@ -112,6 +115,34 @@ slackChannel({
 
 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.
+
+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

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/create-agent.md

@@ -89,7 +89,7 @@ Runtime files created after chat:
 
 ## Handoff To A Coding Agent
 
-The owner does not need to fill a separate brief file. The natural-language request they type into Codex, Claude Code, or another coding agent is the brief.
+The owner does not need to run a brief wizard or fill a separate brief file. The natural-language request they type into Codex, Claude Code, or another coding agent is the brief.
 
 Primary flow:
 
@@ -97,9 +97,9 @@ Primary flow:
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-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.
+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 AgentKit CLI wizard in the normal flow: 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:
+After the owner gives the general idea inside the coding-agent chat, 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."
@@ -108,6 +108,8 @@ 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.
 
+The coding agent should build a testable capsule, not only a prompt. For each meaningful requirement in the brief or `AGENT_SPEC.md`, decide whether it needs a prompt instruction, tool, schema/migration, fixture, eval, direct tool check, or deploy/readiness check. Privacy, confirmation, external writes, bookings, customer data, business hours, dates, and integration failures should have evals or deterministic checks before the capsule is called done.
+
 Optional shortcut when copying a prompt into another coding agent:
 
 ```sh
@@ -176,7 +178,7 @@ 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.
+`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, OpenCode Zen, OpenCode Go, or another supported provider.
 
 ## Safety Rules
 

package/docs/guides/debug-channel.md

@@ -2,7 +2,7 @@
 
 ## Goal
 
-Diagnose website, Telegram, WhatsApp, Discord, or Slack channel setup, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
+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
 
@@ -69,7 +69,7 @@ Expected `show` output includes signature status, dedupe key, queue/run state, o
 
 - 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 a dry-run send, not proof that a client received a message.
+- 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.
 
@@ -117,7 +117,7 @@ The provider retried an already-processed event. No second agent run should be c
 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 built the outbound request in explicit dry-run mode. The provider was not called.
+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.

package/docs/guides/prepare-deploy.md

@@ -154,7 +154,7 @@ npm run agentkit -- chat-ui --deploy
 npm run agentkit -- access token list
 ```
 
-For hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json`. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. The hosted Chat UI shows the conversation id, tool calls, tool errors, and a new-conversation control; use `npm run agentkit -- conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
+For hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json` and prints a production handoff with the deploy URL, UI command, secret status, database/schema artifact, integration connect commands, smoke status, and next recommended command. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. The hosted Chat UI shows the conversation id, tool calls, tool errors, and a new-conversation control; use `npm run agentkit -- conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
 
 When the UI is running, open the printed `Chat:` URL and tell the owner the exact URL. If the capsule is still on `test/fake`, say the UI was tested only with the deterministic fake provider.
 

package/docs/guides/run-evals.md

@@ -22,6 +22,8 @@ Run evals:
 agentkit eval run
 ```
 
+`agentkit eval run` uses temporary local SQLite storage for eval execution. This keeps eval conversations and tool calls isolated from `.agentkit/agentkit.db`, so evals can run while a local chat or dev server is using the normal development database.
+
 If the capsule uses npm scripts and Windows PowerShell blocks `npm.ps1`, use:
 
 ```sh
@@ -54,6 +56,8 @@ Create or edit:
 evals/<name>.eval.ts
 ```
 
+Create evals proactively from the agent brief and `AGENT_SPEC.md`. High-value evals cover identity and scope, required intake fields, confirmation before writes, no-leak/privacy rules, timezone and business-hour behavior, default durations or limits, tool-call payloads, unavailable slots, empty results, missing auth, rate limits, and timeouts. If a real conversation reveals a bug, add the smallest regression eval that would have failed before the fix.
+
 Use conversations as source material:
 
 ```txt
@@ -152,7 +156,7 @@ export default defineEval({
 });
 ```
 
-`tools.persisted` validates the tool call saved in local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`.
+`tools.persisted` validates the tool call saved in the eval run's local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`.
 
 Use `tools.count` for the exact number of persisted calls in that turn, `tools.calledOnce` for exactly one call by name, and `tools.order` for required relative order. `tools.order` allows extra calls before, between, or after the named calls; pair it with `tools.count` when the exact call set matters.