@andreprado/agentkit 0.1.0-alpha.10

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

@@ -0,0 +1,243 @@
+# 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_id}/{type}/{provider}/webhook`;
+- 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 ID. | Worker routes requests by channel ID, type, and provider. |
+| 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

@@ -0,0 +1,102 @@
+# 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 setup support-whatsapp
+```
+
+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
+```
+
+## 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`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+
+## 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.
+- 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/guides/connect-telegram.md

@@ -0,0 +1,110 @@
+# Connect Telegram
+
+## Goal
+
+Connect a Telegram bot to a hosted AgentKit channel with a stable AgentKit webhook URL.
+
+## When To Use It
+
+Use this after `telegramChannel({ name: "support-telegram" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit channels add telegram support-telegram
+agentkit channels setup support-telegram
+agentkit channels setup support-telegram --apply
+agentkit channels status support-telegram
+agentkit channels test support-telegram --message "hello"
+agentkit channels deliveries list support-telegram
+```
+
+Required secrets:
+
+```txt
+TELEGRAM_BOT_TOKEN
+TELEGRAM_WEBHOOK_SECRET
+```
+
+## Files Created Or Edited
+
+- `agentkit.config.ts`: `telegramChannel({ name: "support-telegram" })`.
+- `.agentkit/deploy.json`: deploy state for resolving the hosted deploy.
+- No local webhook server files.
+
+## Minimal Working Example
+
+```ts
+import { defineAgent, telegramChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [telegramChannel({ name: "support-telegram" })],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+To answer once after a burst of Telegram messages, enable channel buffering:
+
+```ts
+telegramChannel({
+  name: "support-telegram",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 1500,
+    maxWaitMs: 8000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+## Setup Behavior
+
+`agentkit channels setup support-telegram` is read-only and prints the webhook URL.
+
+`agentkit channels setup support-telegram --apply` calls Telegram `setWebhook` with:
+
+- `url`: the AgentKit webhook URL;
+- `secret_token`: `TELEGRAM_WEBHOOK_SECRET`;
+- `allowed_updates`: `["message"]`.
+
+Against AgentKit Cloud, `--apply` runs through the Cloud API and uses managed hosted secrets. The legacy local fallback only uses `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET` from the shell when the Cloud API does not expose channel setup.
+
+## Safety Rules
+
+- Use `--apply` only when real Telegram secrets are present.
+- Do not paste the bot token into code, docs, test fixtures, or delivery logs.
+- Telegram webhook validation uses `X-Telegram-Bot-Api-Secret-Token`.
+
+## Verification
+
+```sh
+agentkit channels status support-telegram
+agentkit channels test support-telegram --message "hello"
+agentkit channels deliveries show <delivery-id>
+```
+
+Expected webhook URL shape:
+
+```txt
+https://<deploy-host>/channels/chn_<id>/telegram/webhook
+```
+
+## Troubleshooting
+
+`TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET must be set`:
+Set both secrets before using `--apply`.
+
+`channel_signature_invalid`:
+The incoming Telegram secret token does not match `TELEGRAM_WEBHOOK_SECRET`.
+
+`channel_payload_invalid`:
+The update is malformed or is not a supported private text message.

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

@@ -0,0 +1,119 @@
+# Connect WhatsApp Through Zapster
+
+## Goal
+
+Connect a Zapster WhatsApp account to a hosted AgentKit WhatsApp channel.
+
+## When To Use It
+
+Use this after `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit channels add whatsapp support-whatsapp --provider zapster
+agentkit channels setup support-whatsapp
+agentkit channels status support-whatsapp
+agentkit channels test support-whatsapp --message "hello"
+agentkit channels deliveries list support-whatsapp --since 24h
+```
+
+Required secrets:
+
+```txt
+ZAPSTER_API_KEY
+ZAPSTER_INSTANCE_ID
+ZAPSTER_WEBHOOK_ID
+```
+
+Optional hardening secret:
+
+```txt
+ZAPSTER_WEBHOOK_TOKEN
+```
+
+## Files Created Or Edited
+
+- `agentkit.config.ts`: `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })`.
+- `.agentkit/deploy.json`: deploy state for resolving the hosted deploy.
+- 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" },
+});
+```
+
+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,
+  },
+})
+```
+
+## 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/chn_<id>/whatsapp/zapster/webhook
+```
+
+If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, register the Zapster URL with the token as a query parameter:
+
+```txt
+https://<deploy-host>/channels/chn_<id>/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.
+- Use optional `ZAPSTER_WEBHOOK_TOKEN` in the webhook URL when the endpoint should require an extra secret known only to AgentKit and Zapster.
+- Unsupported media should be logged as skipped/unsupported without creating an agent run.
+
+## 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>
+```
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `ZAPSTER_WEBHOOK_ID` as hosted managed secrets. If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, set that managed secret too.
+
+`channel_signature_invalid`:
+Zapster is not sending the expected instance/webhook IDs, or the optional 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.