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

package/docs/guides/channels-implementation-map.md

@@ -1,243 +0,0 @@
-# Channels Implementation Map
-
-Source of truth: [`../../CHANNELS_PRD.md`](../../CHANNELS_PRD.md).
-
-Use this map before implementing Channels. It identifies the current AgentKit files that should absorb the Channels contract and the blocker order from `TASKS.md`.
-
-## Current State
-
-AgentKit already has the hosted deploy spine that Channels should extend:
-
-- Public config and exports live in `packages/agentkit/src/index.ts`.
-- Config loading and validation live in `packages/agentkit/src/runtime/config.ts`.
-- `agentkit inspect` state lives in `packages/agentkit/src/runtime/inspect.ts`.
-- Cloudflare artifact generation lives in `packages/agentkit/src/runtime/targets/cloudflare/build.ts`.
-- The CLI command switch lives in `packages/agentkit/src/cli/index.ts`.
-- Local AgentKit Cloud control-plane routes live in `packages/agentkit/src/runtime/deploy.ts`.
-- Local runtime conversation storage lives in `packages/agentkit/src/storage/sqlite.ts`.
-
-Channels should not start inside provider-specific code. The obvious implementation path is contract-first, fixture-first, then hosted ingress.
-
-## First Files To Edit
-
-### Config Contract
-
-Edit `packages/agentkit/src/index.ts` first.
-
-Add:
-
-- `AgentChannel`;
-- `WebsiteChannelConfig`;
-- `TelegramChannelConfig`;
-- `WhatsappChannelConfig`;
-- `ChannelType`;
-- `ChannelProvider`;
-- `websiteChannel(...)`;
-- `telegramChannel(...)`;
-- `whatsappChannel(...)`;
-- optional `channels?: AgentChannel[]` on `AgentConfig`.
-
-Reason: generated capsules import public helpers from `@andreprado/agentkit`, so the public contract must exist before config validation, templates, docs, or CLI commands can rely on it.
-
-### Config Validation
-
-Edit `packages/agentkit/src/runtime/config.ts` after the public types exist.
-
-Add validation for:
-
-- lowercase stable channel names;
-- unique names within a capsule;
-- supported type/provider combinations;
-- required channel secret name arrays;
-- `runtime: "edge"` when channels are configured for hosted use;
-- no secret values in channel config.
-
-Tests belong in `packages/agentkit/src/runtime/config.test.ts`.
-
-### Inspect State
-
-Edit `packages/agentkit/src/runtime/inspect.ts` after validation.
-
-Add:
-
-- channel summaries;
-- channel required secrets merged into the existing `secrets` status map;
-- no provider API values or webhook secret values.
-
-Tests belong in `packages/agentkit/src/runtime/config.test.ts` or a new focused inspect test if the file grows too large.
-
-### Build Manifest
-
-Edit `packages/agentkit/src/runtime/targets/cloudflare/build.ts` after inspect.
-
-Add channels to:
-
-- `AgentManifest`;
-- `buildManifest(...)`;
-- generated Worker manifest JSON;
-- warning text if a channel needs hosted bindings that the current artifact cannot run yet.
-
-The generated Worker should not perform real channel processing until ingress/queue tasks land, but the manifest must carry enough metadata for the control plane to create resources.
-
-Tests belong in `packages/agentkit/src/runtime/build.test.ts`.
-
-## New Runtime Modules
-
-Add `packages/agentkit/src/runtime/channels.ts` for normalized types and registry-level helpers.
-
-It should own:
-
-- `RawWebhookEvent`;
-- `NormalizedChannelEvent`;
-- `NormalizedChannelMessage`;
-- `ChannelAdapter`;
-- `ChannelSendInput`;
-- `ChannelSendResult`;
-- `WebhookVerificationInput`;
-- `WebhookVerificationResult`;
-- `ChannelStatusInput`;
-- `ChannelStatusResult`;
-- adapter lookup by channel type/provider;
-- shared secret redaction helpers if they are not already generic.
-
-Add adapter modules under `packages/agentkit/src/runtime/channels/`:
-
-- `website.ts`;
-- `telegram.ts`;
-- `whatsapp-zapster.ts`;
-- `whatsapp-meta.ts` as a compatibility stub.
-
-Add fixtures under `packages/agentkit/src/runtime/fixtures/channels/`:
-
-- `website-message.json`;
-- `telegram-message.json`;
-- `telegram-unsupported-update.json`;
-- `zapster-message.json`;
-- `zapster-unsupported-media.json`;
-- duplicate-event variants where useful.
-
-Default tests must use these fixtures and fake fetchers only.
-
-## CLI Entry Points
-
-Edit `packages/agentkit/src/cli/index.ts` only after config/build/control-plane basics exist.
-
-Add a `channels` command with subcommands:
-
-- `list`;
-- `add`;
-- `setup`;
-- `status`;
-- `test`;
-- `deliveries list`;
-- `deliveries show`.
-
-Keep command behavior split:
-
-- Before deploy: read local capsule config and explain missing deploy/setup state.
-- After deploy: read `.agentkit/deploy.json` and call the AgentKit Cloud API.
-
-Do not make the CLI mutate real Telegram/Zapster settings in default tests. Provider mutations need explicit credentials and opt-in smoke gates.
-
-## Control Plane
-
-Edit `packages/agentkit/src/runtime/deploy.ts` after manifest and CLI contracts are clear.
-
-Current control-plane API only serves:
-
-- `GET /health`;
-- `POST /v1/deploys`.
-
-Add:
-
-- `POST /v1/deploys/{deploy_id}/channels`;
-- `GET /v1/deploys/{deploy_id}/channels`;
-- `GET /v1/channels/{channel_id}`;
-- `DELETE /v1/channels/{channel_id}`;
-- public webhook routes for `/channels/{channel_name}/{type}/{provider}/webhook`, with old `chn_*` routes accepted for compatibility;
-- delivery inspection routes for CLI use.
-
-The local `npm run agentkit:operator -- serve` path can use an in-memory or local SQLite fake store first. Production Postgres support can follow once the contract is tested. In both stores, persist only secret names and statuses, never secret values.
-
-## Hosted Worker And Cloudflare Bindings
-
-Edit `packages/agentkit/src/runtime/targets/cloudflare/build.ts` when adding real hosted ingress.
-
-The Worker currently handles:
-
-- `GET /_agentkit`;
-- `GET /`;
-- `POST /chat`;
-- Turso health/query helpers;
-- R2 file routes.
-
-Channels will need:
-
-- a channel ingress route;
-- raw body preservation for verification;
-- a channel coordination Durable Object for dedupe and identity mapping;
-- Cloudflare Queue producer and consumer bindings;
-- delivery state persistence or calls back to AgentKit Cloud;
-- redaction-aware logs.
-
-Do not put AgentKit channel plumbing in the user's Turso database. Turso remains only for the user's agent application tables.
-
-## Storage Boundary Decision
-
-For local tests, use the AgentKit Cloud fake/control-plane store for channel resource metadata and delivery records.
-
-Use this boundary for V1 local cloud tests:
-
-| Record | Local `npm run agentkit:operator -- serve` store | Generated Worker / Durable Object / Queue contract |
-| --- | --- | --- |
-| Channel resource metadata | Yes: `channels` table or equivalent fake store keyed by `chn_...`. | Read-only manifest input after deploy. |
-| Channel secret references | Yes: names and `set`/`missing` status only. | Runtime receives injected secret values by name; no readback. |
-| Channel endpoint URL | Yes: generated from deploy URL plus stable channel name. | Worker forwards deploy ID and routes requests by channel name, type, and provider; old `chn_*` URLs remain compatibility routes. |
-| Channel delivery records | Yes: `deliveries` table keyed by `del_...` for CLI inspection. | Worker/consumer reports state transitions back to control plane or durable storage. |
-| Channel event audit records | Yes: compact event records keyed by `chevt_...`, with redacted provider metadata. | Ingress creates or reports event records after provider validation. |
-| External identity mappings | Fake DO-compatible store for local tests, keyed by `chid_...`. | Durable Object owns strongly consistent identity to conversation mapping. |
-| Dedupe keys | Fake DO-compatible store with default 14-day retention. | Durable Object owns deterministic dedupe keys and retention. |
-| Per-conversation ordering/backpressure | Fake DO-compatible store only when tests need it. | Durable Object owns locks and short-lived backpressure state. |
-| Queue payloads | In-memory fake queue drained by tests. | Cloudflare Queue owns async ingress to consumer handoff. |
-| Raw payload/media blobs | Do not persist by default in local tests; use fixtures. | R2 stores large raw payloads, media, exports, and debug bundles. |
-| User application data | Never. | Never. User application tables stay in Turso. |
-
-Use Durable Object-compatible abstractions for:
-
-- dedupe keys;
-- external identity to conversation ID mappings;
-- ordering/backpressure state.
-
-This keeps the implementation aligned with the production architecture while allowing deterministic tests without real Cloudflare bindings.
-
-The first implementation should prefer an in-memory fake store for tests unless persistence across local control-plane restarts is being tested. Production Postgres can mirror the same resource/delivery tables later, after API behavior is stable.
-
-## Implementation Order
-
-Start with the unblocked tasks from `TASKS.md`:
-
-1. CH-01: decide the final local fake store shape.
-2. CH-02: add public channel config helpers.
-3. CH-03: validate `channels` config.
-4. CH-04: include channels in inspect/build manifests.
-5. CH-05 and CH-06: add normalized runtime types and fixture-first adapter tests.
-
-Do not begin channel CRUD or ingress until CH-04 exists. The control plane needs channel metadata in the build manifest, otherwise hosted resources are disconnected from the deploy artifact.
-
-## Test Strategy
-
-Default verification should stay offline:
-
-```sh
-bun test
-npm run typecheck
-```
-
-Provider tests should be opt-in:
-
-```sh
-AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
-AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
-```
-
-Real-provider smoke tests must document required secret names and must never print secret values.

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 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.