@andreprado/agentkit 0.1.0-alpha.17 → 0.1.0-alpha.18

package/docs/guides/channels-production-handoff.md

@@ -1,118 +0,0 @@
-# Channels Production Handoff
-
-## Goal
-
-Move Channels from local fake control-plane tests to production safely.
-
-## Deployment Order
-
-1. Build and typecheck:
-
-```sh
-npm run typecheck
-bun test
-agentkit build --target cloudflare
-```
-
-2. Deploy AgentKit Cloud/control plane with:
-
-```txt
-Cloudflare Worker
-Cloudflare Queue for channel jobs
-Durable Object namespace for channel coordination
-R2 bucket for large/raw payload handoff when enabled
-Turso/Postgres control-plane tables for deploys, channels, deliveries, events, and identities
-```
-
-3. Set managed secrets:
-
-```txt
-OPENAI_API_KEY or another model provider key
-TELEGRAM_BOT_TOKEN
-TELEGRAM_WEBHOOK_SECRET
-ZAPSTER_API_KEY
-ZAPSTER_INSTANCE_ID
-ZAPSTER_WEBHOOK_ID
-META_WHATSAPP_ACCESS_TOKEN
-META_WHATSAPP_APP_SECRET
-META_WHATSAPP_VERIFY_TOKEN
-```
-
-4. Create channels:
-
-```sh
-agentkit channels add telegram support-telegram
-agentkit channels add whatsapp support-whatsapp --provider zapster
-agentkit channels setup support-telegram --apply
-agentkit channels connect whatsapp support-whatsapp --provider zapster
-```
-
-5. Run smoke checks:
-
-```sh
-agentkit channels status support-telegram
-agentkit channels test support-telegram --message "hello"
-agentkit channels status support-whatsapp
-agentkit channels test support-whatsapp --message "hello"
-agentkit channels deliveries list support-telegram --since 1h
-agentkit channels deliveries list support-whatsapp --since 1h
-agentkit channels buffers list support-whatsapp
-```
-
-After deploy, record this exact handoff block:
-
-```txt
-Deploy URL: https://<deploy-host>
-Telegram channel URL: https://<deploy-host>/channels/support-telegram/telegram/telegram/webhook
-Zapster channel URL: https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook
-Required provider webhook settings: Telegram setWebhook URL/secret token; Zapster webhook URL plus optional ZAPSTER_WEBHOOK_TOKEN query parameter
-Required managed secrets: TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET, ZAPSTER_API_KEY, ZAPSTER_INSTANCE_ID, ZAPSTER_WEBHOOK_ID
-Smoke commands: agentkit channels doctor <name>; agentkit channels test <name> --message "hello"; agentkit channels test-audio <name> --fixture voice-note for audio channels; agentkit transcribe smoke --provider groq for transcription; agentkit channels deliveries list <name> --since 1h
-Rollback command: curl -X DELETE "$AGENTKIT_CLOUD_API_URL/v1/channels/<channel-id>" -H "Authorization: Bearer $AGENTKIT_CLOUD_API_TOKEN"; then remove provider webhook registration before rolling back the Worker
-Known unverified items: any channel with no real provider inbound, no provider_sent outbound, stale buffers, or AGENTKIT_CHANNEL_SEND_DRY_RUN=1
-```
-
-## Local Fake Versus Real Provider Gates
-
-Default tests are offline and must pass without provider credentials:
-
-```sh
-bun test
-```
-
-Real-provider smoke tests are opt-in:
-
-```sh
-AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
-AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
-```
-
-Telegram smoke requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
-
-Zapster smoke requires `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `AGENTKIT_ZAPSTER_TO`. `AGENTKIT_ZAPSTER_SEND_URL` is optional and defaults to `https://api.zapsterapi.com/v1/wa/messages`.
-
-## Smoke Checks
-
-- Unknown channel ID returns `404` and creates no tenant record.
-- Invalid Telegram signature or Zapster origin headers return `401` and create a failed delivery.
-- Duplicate provider event returns `200` with `duplicate` and creates no second queue job.
-- Accepted inbound text creates one queue job and one outbound delivery.
-- Real outbound success is `provider_sent` and includes a provider message ID. `adapter_stubbed` means dry-run mode built a request but did not call the provider.
-- Buffered inbound bursts stay in `buffered` state, then flush into one queue job and one outbound delivery.
-- Retryable failures dead-letter after the configured retry ceiling.
-- `channel_limit_exceeded` does not create queue backlog.
-
-## Rollback
-
-- Disable the channel resource first; do not delete delivery history.
-- Remove provider webhook registration if the provider keeps retrying.
-- Roll back the Worker only after queue drain or pause.
-- Keep managed secrets; rotate only if a secret may have leaked.
-
-## Production Defaults
-
-- Start with conservative per-channel daily message and cost limits.
-- For WhatsApp and Telegram agents that receive rapid client message bursts, start with `buffer.mode: "debounce"`, `quietWindowMs` between `1500` and `2500`, `maxWaitMs` between `8000` and `12000`, and strict `maxMessages`/`maxChars`.
-- Keep raw body storage disabled unless there is an explicit encrypted R2 retention policy.
-- Delivery APIs return hashes and redacted metadata, not payload bodies.
-- Turso remains reserved for the user's agent application data, not AgentKit channel plumbing.

package/docs/portable-deploy-release-checklist.md

@@ -1,41 +0,0 @@
-# Portable Deploy Release Checklist
-
-Run this before merging portable deploy target work.
-
-## Tests
-
-```sh
-bun test
-npm run typecheck
-npm run agentkit -- build --target cloudflare
-npm run agentkit -- build --target container
-npm run agentkit -- deploy --target vps --host agent.example.com --dry-run
-docker compose -f .agentkit/build/vps/compose.yaml config
-```
-
-## Smoke
-
-- Cloudflare build contains `worker.js`, `wrangler.jsonc`, `durable-object-schema.sql`, and `agent.manifest.json`.
-- Container build contains `server.js`, `Dockerfile`, `migrations/`, and `agent.manifest.json`.
-- VPS build contains `compose.yaml`, `.env.production.example`, `SECRETS.md`, and `PRODUCTION_HANDOFF.md`.
-- `/health`, `/_agentkit`, `/chat`, `/tools/:name`, `/files/:key`, and channel webhook fixtures pass on the local/container runtime.
-
-## Secrets
-
-```sh
-rg -n "sk-|OPENAI_API_KEY=.*[A-Za-z0-9]" .agentkit/build || true
-```
-
-Expected: no secret values. Generated files may contain secret names only.
-
-## Production Handoff
-
-- Cloudflare deploy has target-aware `.agentkit/deploy.json` with `target`, `runtime`, and `resources`.
-- VPS handoff documents `PORT`, `AGENTKIT_SQLITE_PATH`, reverse proxy expectations, smoke checks, SQLite backup, Postgres upgrade path, and rollback.
-- Rollback command is present in `.agentkit/build/vps/PRODUCTION_HANDOFF.md`.
-
-## External Smokes
-
-- Cloudflare deployed smoke requires Cloudflare credentials and a provider key.
-- Docker image smoke requires a running Docker daemon.
-- Telegram/Zapster real send smoke requires explicit provider credentials.