@andreprado/agentkit 0.1.1 → 0.2.0

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

@@ -1,139 +1,11 @@
-# Connect WhatsApp Through UAZAPI
+# Connect WhatsApp Through UAZAPI Locally
 
-## Goal
+Add `whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })` to `channels` with `runtime: "local"`. Set `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, and `UAZAPI_WEBHOOK_TOKEN` in ignored `.env`.
 
-Connect a UAZAPI WhatsApp instance to an AgentKit WhatsApp channel locally or when hosted.
+Generate `UAZAPI_WEBHOOK_TOKEN` yourself; it is not issued by UAZAPI. Register `https://<tunnel-host>/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>` with `addUrlEvents: false` and `addUrlTypesMessages: false`. Keep the complete tokenized URL secret. The API base URL must be public HTTPS; private-network targets are rejected before forwarding credentials.
 
-## When To Use It
+AgentKit ignores fromMe/wasSentByApi messages. Replies use `/send/text`. Audio transcription requires top-level `transcription` and channel `audio: { mode: "transcribe" }`; media comes from `/message/download` with `return_base64: true`, never an arbitrary webhook-provided URL.
 
-Use this after `whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })` exists in `agentkit.config.ts`.
+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
-node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | agentkit env set UAZAPI_WEBHOOK_TOKEN --stdin
-agentkit dev
-```
-
-Required secrets:
-
-```txt
-UAZAPI_BASE_URL
-UAZAPI_TOKEN
-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" },
-});
-```
-
-## Local Usage
-
-`UAZAPI_WEBHOOK_TOKEN` is an AgentKit-owned secret, not a token issued by UAZAPI. Generate a different value for every channel and keep it in the ignored local `.env`:
-
-```sh
-node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | npm run agentkit -- env set UAZAPI_WEBHOOK_TOKEN --stdin
-npm run agentkit -- env set UAZAPI_BASE_URL --stdin
-npm run agentkit -- env set UAZAPI_TOKEN --stdin
-npm run agentkit -- dev
-```
-
-Expose the printed local port through an HTTPS tunnel, then register this exact URL with UAZAPI:
-
-```txt
-https://<tunnel-host>/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>
-```
-
-Configure UAZAPI with `addUrlEvents: false` and `addUrlTypesMessages: false` so it calls that exact URL. AgentKit allows a public tunnel host only on authenticated channel webhook paths; local chat, inspect, tools, files, and conversation APIs remain loopback-only.
-
-Send a real WhatsApp message after registration. A `200` response proves UAZAPI preserved the tokenized URL and AgentKit accepted it. A `channel_signature_invalid` response means the configured URL omitted, changed, or stripped the token. If the tunnel hostname changes, update the registered webhook URL.
-
-## Hosted 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
-```
-
-AgentKit requires `UAZAPI_WEBHOOK_TOKEN` and 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`.
-- Keep `UAZAPI_WEBHOOK_TOKEN` configured. UAZAPI V1 has no body-signature contract, so AgentKit rejects webhooks without the secret query token.
-- UAZAPI does not expose a documented webhook body-signature contract in AgentKit V1; the AgentKit-owned query token is the authentication layer.
-- Treat the complete tokenized URL as a secret and rotate `UAZAPI_WEBHOOK_TOKEN` if it appears in logs or screenshots.
-- 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`, `UAZAPI_TOKEN`, and `UAZAPI_WEBHOOK_TOKEN` as secrets.
-
-`channel_signature_invalid`:
-The required 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.
+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-zapster.md

@@ -1,207 +1,11 @@
-# Connect WhatsApp Through Zapster
+# Connect WhatsApp Through Zapster Locally
 
-## Goal
+Add `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })` to `channels` with `runtime: "local"`. Set `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, `ZAPSTER_WEBHOOK_ID`, and `ZAPSTER_WEBHOOK_TOKEN` in ignored `.env`.
 
-Connect a Zapster WhatsApp account to an AgentKit WhatsApp channel locally or when hosted.
+Generate `ZAPSTER_WEBHOOK_TOKEN` yourself and register `https://<tunnel-host>/channels/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>`. AgentKit checks expected instance/webhook IDs and the secret token. Metadata headers alone are not cryptographic authentication. Keep the tokenized URL secret and rotate it if exposed.
 
-## When To Use It
+AgentKit normalizes message.received envelopes and sends replies through Zapster's messages API. Audio transcription requires top-level `transcription` and channel `audio: { mode: "transcribe" }`. The payload must provide a trusted Zapster HTTPS media URL; a media ID alone is insufficient. Arbitrary media hosts are rejected before credentials are sent.
 
-Use this after `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })` exists in `agentkit.config.ts`.
+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
-node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | agentkit env set ZAPSTER_WEBHOOK_TOKEN --stdin
-agentkit dev
-```
-
-Required secrets:
-
-```txt
-ZAPSTER_API_KEY
-ZAPSTER_INSTANCE_ID
-ZAPSTER_WEBHOOK_ID
-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
-
-- `agentkit.config.ts`: `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })`.
-- `.env`: ignored local provider credentials and the AgentKit-owned webhook token.
-- `.agentkit/deploy.json`: deploy state only when using the hosted workflow.
-- No user-managed webhook server.
-
-## 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: "zapster" })],
-  access: { mode: "public" },
-  storage: { driver: "agentkit" },
-});
-```
-
-## Local Usage
-
-`ZAPSTER_WEBHOOK_TOKEN` is an AgentKit-owned secret, not a token issued by Zapster. Generate a different value for every channel and keep it in the ignored local `.env`:
-
-```sh
-node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | npm run agentkit -- env set ZAPSTER_WEBHOOK_TOKEN --stdin
-npm run agentkit -- env set ZAPSTER_API_KEY --stdin
-npm run agentkit -- env set ZAPSTER_INSTANCE_ID --stdin
-npm run agentkit -- env set ZAPSTER_WEBHOOK_ID --stdin
-npm run agentkit -- dev
-```
-
-Expose the printed local port through an HTTPS tunnel, then register this exact URL with Zapster:
-
-```txt
-https://<tunnel-host>/channels/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>
-```
-
-Zapster stores a complete webhook URL and sends `X-Instance-ID` and `X-Webhook-ID` with deliveries. AgentKit requires both expected IDs and the URL secret because those identifiers alone are not cryptographic authentication. AgentKit allows a public tunnel host only on authenticated channel webhook paths; local chat, inspect, tools, files, and conversation APIs remain loopback-only.
-
-Send a real WhatsApp message after registration. A `200` response proves Zapster preserved the tokenized URL and AgentKit accepted it. A `channel_signature_invalid` response means the URL token or expected Zapster IDs did not match. If the tunnel hostname changes, update the registered webhook URL.
-
-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 required 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.
-
-## Hosted Setup Behavior
-
-`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/support-whatsapp/whatsapp/zapster/webhook
-```
-
-AgentKit requires `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 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.
-- Keep `ZAPSTER_WEBHOOK_TOKEN` in the webhook URL. Zapster's metadata headers are not a shared-secret signature, so AgentKit rejects webhooks without the secret query token.
-- Treat the complete tokenized URL as a secret and rotate `ZAPSTER_WEBHOOK_TOKEN` if it appears in logs or screenshots.
-- 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
-
-```sh
-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`, `ZAPSTER_INSTANCE_ID`, `ZAPSTER_WEBHOOK_ID`, and `ZAPSTER_WEBHOOK_TOKEN` as secrets.
-
-`channel_signature_invalid`:
-Zapster is not sending the expected instance/webhook IDs, or the required 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.
+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/create-agent.md

@@ -120,7 +120,7 @@ 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.
+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 local config and secret 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:
 
@@ -138,7 +138,7 @@ import { defineAgent } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "demo",
-  runtime: "edge",
+  runtime: "local",
   provider: {
     name: "test",
     model: "fake",
@@ -153,13 +153,12 @@ export default defineAgent({
     driver: "agentkit",
     path: ".agentkit/agentkit.db",
     database: {
-      driver: "turso",
+      driver: "sqlite",
       schema: "./schema.sql",
     },
     files: {
-      driver: "r2",
-      bucket: "agentkit-demo-files",
-      prefix: "demo",
+      driver: "local",
+        prefix: "demo",
     },
   },
 });
@@ -181,14 +180,8 @@ 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, OpenCode Zen, OpenCode Go, or another supported provider.
 
@@ -243,5 +236,3 @@ Check the `instructions` path in `agentkit.config.ts`.
 Use `blank` or `support`. `research` is planned but not implemented.
 
 ## Backend Contracts Used
-
-Local commands use local files and SQLite. Hosted deploy sends a build artifact to AgentKit Cloud with `agentkit deploy`; users do not create hosted projects or infrastructure by hand.

package/docs/guides/debug-channel.md

@@ -1,159 +1,7 @@
-# Debug A Channel
+# Debug Local Channels
 
-## Goal
+Run `agentkit inspect` and `agentkit channels list` to check configuration and missing secret names. Start `agentkit dev`, POST an authenticated fixture to the local webhook route, and inspect its response and conversation trace. Buffers are in memory; there is no delivery dashboard or buffer-management API. Synthetic tests do not prove a real provider can deliver or receive messages.
 
-Diagnose website, Telegram, WhatsApp, Discord, Slack, generic inbound webhook, generic outbound webhook, cross-channel reply routing, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
+For real traffic, check the tunnel URL, configured provider webhook, signature or secret token, and provider credentials. Tunnel hostnames are accepted only on authenticated webhook routes. Check the conversation trace with `agentkit conversations trace <id>`. Keep raw payloads, phone numbers, credentials, and tokenized URLs out of reports.
 
-## When To Use It
-
-Use this when a hosted channel is not responding, a provider is retrying messages, audio transcription is failing, cross-channel replies are going to the wrong target, 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 deliveries list <reply-target-name> --since 24h
-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.
-- For `replyTo` routes, inspect the source channel delivery for validation, dedupe, buffer, queue, and agent-run state, then inspect the target channel delivery for the outbound provider result.
-- Generic output webhook channels do not have inbound endpoints. Use `agentkit channels doctor <name>` to inspect secret readiness and inspect target-channel deliveries after a source event triggers the route.
-- 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 without `replyTo`.
-
-`provider_sent`:
-The provider API accepted the outbound request and returned a provider message ID. For cross-channel replies, this status appears on the reply target channel, such as WhatsApp or a generic output webhook.
-
-`channel_reply_target_missing`:
-The source channel has `replyTo.channel`, but the hosted channel resource for that target does not exist in the same deploy. Create or reconnect the target channel, then retry the source event.
-
-`channel_reply_recipient_missing`:
-The route needs a destination identity but `recipientFrom` was missing, resolved to an empty value, or the source identity cannot be reused by the target channel. Check the inbound payload and the configured dotted JSON path.
-
-`channel_reply_target_invalid`:
-The route points to an invalid target, such as an inbound-only generic webhook, or tries to use `recipientFrom` for a provider that requires native source identities such as Discord or Slack.
-
-`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.
+For cross-channel replies, check `replyTo.channel`, recipient routing, destination credentials, and outbound provider result. Use `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` for tests that must not send real messages.

package/docs/guides/improve-local.md

@@ -0,0 +1,13 @@
+# Improve From Local Conversations
+
+Collect a reproducible bundle before changing the capsule:
+
+```sh
+agentkit improve collect --since 24h
+agentkit improve collect --conversation-id <id>
+agentkit improve evals .agentkit/improve/<run>
+agentkit replay .agentkit/improve/<run> --against local
+agentkit eval run
+```
+
+Bundles contain local conversation traces and a report. Review them for sensitive data before sharing. Change capsule prompts, tools, or schema, then rerun the regression eval and replay. Generated evals guard external writes through the eval runtime; keep deterministic fixtures for external services. Never upload `.env` or the SQLite database.

package/docs/guides/local-only-migration.md

@@ -0,0 +1,35 @@
+# Upgrade To Local-Only AgentKit
+
+AgentKit 0.2.0 runs capsules locally. This breaking upgrade removes account/billing commands, deployment targets, remote secrets, remote conversation collection, managed Composio, and the remote chat UI.
+
+Before upgrading a working capsule, back up its configuration and local state. Existing local database and file paths remain unchanged.
+
+## Revoke Hosted Credentials Before Upgrading
+
+The old CLI saved the account login token in `~/.agentkit/cloud.json`. Each deployed capsule may also contain `.agentkit/chat-access-token.json`, holding a hosted deploy access token. This upgrade leaves both files untouched. Removing a file or running the old `logout` command only removes a local copy; it does not revoke the live credential.
+
+While the hosted service is still available, use your previous hosted-capable CLI and its configured API endpoint to:
+
+1. From each deployed capsule, run `agentkit access token list`, then `agentkit access token revoke <token-id>` for its retired deploy tokens, including the saved chat token and any tokens exported for other clients. Keep the existing deployment state until this is done.
+2. Run `agentkit account token list`, then `agentkit account token revoke <token-id>` for retired account tokens. Revoke the credential used for these operations last.
+3. Confirm successful server-side revocation before removing `~/.agentkit/cloud.json`, each capsule's `.agentkit/chat-access-token.json`, and any exported copies. Remove old `AGENTKIT_CLOUD_API_TOKEN` values from shell profiles or secret stores too.
+
+Do this before the hosted service is retired; 0.2.0 has no `logout`, `account`, or `access` commands. If you already upgraded, use the previous CLI in a separate environment or ask the hosted-service operator to revoke the credentials. If the service is unreachable, deleting local files cannot establish that tokens were revoked. Never paste token values into chat, tickets, or logs.
+
+## Update The Capsule
+
+1. Set `runtime: "local"` in `agentkit.config.ts`.
+2. For application schemas/migrations, change `storage.database.driver` from `"turso"` to `"sqlite"`. Keep `schema`, `migrations`, and the storage path unchanged.
+3. Change `storage.files.driver` from `"r2"` to `"local"` and remove `bucket`. Keep the prefix and size limit.
+4. Remove `integrations`; implement external-service calls through `defineTool` with your own local credentials. The `composioManaged` helper is removed.
+5. Put required secret values in ignored `.env` using `agentkit env set <NAME> --stdin`. Secret values are never recovered automatically from a remote service.
+6. Run `agentkit skills sync`, remove obsolete `skills/agentkit-deploy` and `skills/agentkit-integrations` files after checking for your own edits, and update capsule instructions that mention removed commands.
+7. Run `agentkit inspect`, `agentkit eval run`, and `agentkit dev`.
+
+Use `agentkit open` for the local UI. Collect local traces with `agentkit improve collect`; remote `--deploy`, `--api`, and `--target` options are rejected. Channel configuration remains in the capsule. Register provider webhooks manually against an HTTPS tunnel while the local process runs. Discord Gateway connections are not managed by AgentKit: bot-mode channels need your own bridge and produce an inspect warning; use interactions for the standard local setup.
+
+## Update Authenticated HTTP Clients
+
+The legacy `x-agentkit-deploy-access-token` header is no longer accepted. Clients that send only this header to an endpoint enforcing token access now receive HTTP 401. Send `Authorization: Bearer <local-token>` or `x-agentkit-access-token: <local-token>` instead. Use the locally configured `AGENTKIT_PRIVATE_TOKEN` for private/admin endpoints or `AGENTKIT_ACCESS_TOKEN` for token-mode chat; hosted account/deploy tokens do not become local credentials automatically. Default loopback-only local access is unchanged.
+
+This upgrade does not delete remote deployments, databases, accounts, or local credential files. Remote data is not copied into local storage. Retire any existing remote resources separately after handling the data you need.

package/docs/guides/replay-local-traces.md

@@ -0,0 +1,11 @@
+# Replay Local Traces
+
+Collect evidence with `agentkit improve collect`, then run:
+
+```sh
+agentkit improve evals .agentkit/improve/<run>
+agentkit replay .agentkit/improve/<run> --against local
+agentkit eval run
+```
+
+Replay uses isolated eval storage and identifies failures per conversation. Tools must check `ctx.runtime.environment === "eval"` and return deterministic fixtures instead of external writes. Inspect the bundle before sharing; redaction does not replace human review.