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

package/docs/guides/agentkit-skills-architecture.md

@@ -1,472 +0,0 @@
-# AgentKit Skills Architecture
-
-## Recommendation
-
-Ship AgentKit skills as the default interface for the user's coding agent, while keeping the docs as the canonical source of truth.
-
-The current docs remain authoritative:
-
-```txt
-docs/llms.txt          short router
-docs/llms-full.txt     complete operating contract
-docs/guides/*.md       task guides
-```
-
-Skills should become the context-efficient working surface:
-
-```txt
-skills/agentkit-capsule/SKILL.md
-skills/agentkit-tools/SKILL.md
-skills/agentkit-deploy/SKILL.md
-...
-```
-
-The default agent path should be:
-
-```txt
-AGENTS.md
-  -> skills/agentkit-capsule/SKILL.md
-    -> one task skill
-      -> one reference, example, or template only when needed
-```
-
-Do not make `llms-full.txt` part of the default handoff. It is the full contract and should be loaded only for ambiguous framework behavior, internals work, or broad audits.
-
-## Problem
-
-`docs/llms-full.txt` is useful but too large for ordinary agent work. Loading it by default spends context on deploy, channels, backend contracts, evals, and storage details even when the owner only asked for a prompt change or one tool.
-
-The generated capsule files and `agentkit handoff` currently tell coding agents to read the full docs path. That is correct for completeness, but not for context economy.
-
-Skills solve this because they use progressive disclosure:
-
-- metadata is always discoverable;
-- `SKILL.md` loads only when the task matches;
-- examples, templates, scripts, and references load only when selected by the skill.
-
-## Product Contract
-
-AgentKit should ship skills out of the box for agents that support repo-local skills.
-
-Generated capsules should include:
-
-```txt
-skills/
-  agentkit-capsule/
-    SKILL.md
-    references/
-      docs-router.md
-```
-
-Template-specific and task-specific skills can live either:
-
-- inside the generated capsule, for maximum out-of-the-box usability; or
-- inside the installed AgentKit package, copied into the capsule by `agentkit new`.
-
-The generated capsule must still include `AGENTS.md`, `AGENTKIT.md`, `CLAUDE.md`, and `README.md` for agents or tools that do not support skills.
-
-## Skill Design Rules
-
-Each `SKILL.md` should be short and procedural. Target 300-800 words.
-
-Every skill should include:
-
-- when to use it;
-- files to inspect;
-- files it may edit;
-- exact commands;
-- safety rules;
-- verification;
-- links to optional references, examples, templates, or assets.
-
-Each skill should avoid:
-
-- duplicating whole guides;
-- copying large code examples into `SKILL.md`;
-- requiring `llms-full.txt` by default;
-- mixing user-capsule workflows with AgentKit maintainer/operator workflows.
-
-Use bundled resources this way:
-
-```txt
-references/   deeper task notes loaded only when needed
-examples/     source examples the agent may inspect
-templates/    starter files the agent may copy and adapt
-scripts/      deterministic helpers for fragile/repeated tasks
-assets/       files used as output resources
-```
-
-## Core Skills To Ship
-
-### agentkit-capsule
-
-The always-first router for work inside an Agent Capsule.
-
-Use when the agent detects `agentkit.config.ts` or the owner asks to build/change an AgentKit agent.
-
-Responsibilities:
-
-- establish the capsule root as the runtime boundary;
-- read `AGENTS.md` or `AGENTKIT.md`;
-- route to one task skill;
-- prefer `agentkit docs llms` over `agentkit docs full`;
-- load `llms-full.txt` only when the task needs the complete contract;
-- run the baseline checks before completion.
-
-Default verification:
-
-```sh
-npm run typecheck
-npm run agentkit -- inspect
-npm run chat -- --message "hello"
-```
-
-### agentkit-build-agent
-
-Use when the owner gives a natural-language brief for a new or changed agent.
-
-Responsibilities:
-
-- translate the brief into prompt, tools, schema, evals, and assumptions;
-- keep the first useful version runnable with `test/fake` unless the owner chooses a real provider;
-- create domain-specific local behavior without waiting for a wizard;
-- add evals for the expected first behavior.
-
-Likely templates:
-
-```txt
-templates/support-agent.instructions.md
-templates/appointment-intake.instructions.md
-templates/sales-qualifier.instructions.md
-templates/internal-operations.instructions.md
-```
-
-### agentkit-prompts
-
-Use when editing `prompts/instructions.md` or designing the agent's behavior.
-
-Responsibilities:
-
-- define role, boundaries, escalation rules, tone, and tool-use policy;
-- prevent false claims about actions not performed;
-- describe when to use Knowledge versus tools;
-- keep user-facing behavior specific to the owner's domain.
-
-Likely templates:
-
-```txt
-templates/knowledge-grounded-faq.instructions.md
-templates/appointment-intake.instructions.md
-templates/support-agent.instructions.md
-```
-
-### agentkit-tools
-
-Use when adding or changing TypeScript tools.
-
-Responsibilities:
-
-- create `defineTool` tools with input/output schemas;
-- register tools in `agentkit.config.ts`;
-- declare tool secrets and permissions;
-- add timeouts;
-- test tools directly;
-- keep eval runs deterministic and non-destructive.
-
-Likely examples:
-
-```txt
-examples/lookup-order.tool.ts
-examples/external-api-lookup.tool.ts
-examples/eval-safe-send-email.tool.ts
-```
-
-Primary reference: `docs/guides/add-tool.md`.
-
-### agentkit-database
-
-Use when adding agent-owned tables or database-backed tools.
-
-Responsibilities:
-
-- edit `schema.sql`;
-- keep schema changes idempotent;
-- use `ctx.db` in tools;
-- avoid local database driver imports;
-- run local migration/seed/shell checks;
-- preserve deploy-compatible `storage.driver: "agentkit"`.
-
-Likely templates:
-
-```txt
-templates/appointments.schema.sql
-templates/leads.schema.sql
-templates/tickets.schema.sql
-templates/notes.schema.sql
-```
-
-Primary reference: `docs/guides/add-tool.md` database section and `docs/guides/prepare-deploy.md`.
-
-### agentkit-knowledge
-
-Use when the agent should answer from committed source files such as FAQs, prices, policies, CSVs, and procedures.
-
-Responsibilities:
-
-- create `knowledge/` sources;
-- configure `knowledge.sources`;
-- choose lexical search by default;
-- configure embeddings only when needed;
-- verify with `knowledge sync` and `knowledge search`;
-- keep secrets and live customer data out of Knowledge.
-
-Likely templates:
-
-```txt
-templates/faq.md
-templates/prices.csv
-templates/policies.md
-```
-
-Primary reference: `docs/guides/add-knowledge.md`.
-
-### agentkit-provider
-
-Use when switching from `test/fake` to a real provider.
-
-Responsibilities:
-
-- ask the owner which provider to use;
-- update `agentkit.config.ts`;
-- update `.env.schema`;
-- set local secrets through AgentKit commands;
-- verify with chat, inspect, and UI;
-- never import provider SDKs into the capsule.
-
-Primary reference: `docs/guides/use-provider.md`.
-
-### agentkit-evals
-
-Use when adding or running evals.
-
-Responsibilities:
-
-- create `evals/*.eval.ts`;
-- use deterministic assertions;
-- verify persisted tool calls;
-- avoid real PII and secrets;
-- guard external side effects with `ctx.runtime.environment === "eval"`;
-- run `npm run eval`.
-
-Likely templates:
-
-```txt
-templates/smoke.eval.ts
-templates/tool-call.eval.ts
-templates/no-leak.eval.ts
-templates/knowledge-answer.eval.ts
-```
-
-Primary reference: `docs/guides/run-evals.md`.
-
-### agentkit-deploy
-
-Use when preparing or running hosted deploy.
-
-Responsibilities:
-
-- run readiness checks;
-- keep hosting target selection inside AgentKit;
-- use managed secrets, not committed `.env`;
-- run `deploy doctor`;
-- run `deploy --smoke`;
-- run hosted UI checks;
-- report production handoff details when deploy is ready.
-
-Primary reference: `docs/guides/prepare-deploy.md`.
-
-### agentkit-security
-
-Use before or during any work involving secrets, external APIs, tools, evals from conversations, public access, channels, or hosted deploys.
-
-Responsibilities:
-
-- prevent `.env`, `.agentkit/`, and secret values from being committed;
-- enforce secret-name-only config;
-- confirm tool secrets and permissions;
-- check access mode assumptions;
-- require redaction for client data.
-
-Primary reference: `docs/guides/security-rules.md`.
-
-### agentkit-channels
-
-Use when adding, connecting, testing, or debugging website, Telegram, or WhatsApp channels.
-
-Responsibilities:
-
-- add channel config helpers;
-- deploy before hosted channel creation;
-- manage provider secret names;
-- verify setup/status/test/delivery logs;
-- separate channels from tools;
-- debug webhook and delivery errors without leaking provider payloads.
-
-Likely references:
-
-```txt
-references/telegram.md
-references/whatsapp-zapster.md
-references/channel-debugging.md
-```
-
-Primary references:
-
-- `docs/guides/add-channel.md`
-- `docs/guides/connect-telegram.md`
-- `docs/guides/connect-whatsapp-zapster.md`
-- `docs/guides/debug-channel.md`
-- `docs/guides/channel-security.md`
-
-### agentkit-troubleshooting
-
-Use when AgentKit commands fail or the agent is unsure which task skill applies.
-
-Responsibilities:
-
-- start from the error code;
-- run `inspect`;
-- check config, secrets, package install, provider, storage, and channel state;
-- route to a more specific skill;
-- load `llms-full.txt` only when narrower references cannot explain the behavior.
-
-Primary reference: `docs/llms-full.txt` troubleshooting section.
-
-## Maintainer-Only Skills
-
-Do not ship these into user capsules by default:
-
-- control-plane deploy;
-- operator dashboard;
-- account grant/revoke;
-- backend contract implementation;
-- Cloudflare/Turso/R2 provisioning internals;
-- release-lane ownership;
-- package publishing.
-
-Those workflows belong in maintainer skills inside the AgentKit repository, not in generated user capsules.
-
-Suggested maintainer skills:
-
-```txt
-skills/agentkit-maintainer-control-plane/
-skills/agentkit-maintainer-channels/
-skills/agentkit-maintainer-release/
-```
-
-## Generated Capsule Shape
-
-V1 generated capsules should contain:
-
-```txt
-AGENTS.md
-AGENTKIT.md
-CLAUDE.md
-README.md
-skills/
-  agentkit-capsule/
-    SKILL.md
-    references/
-      docs-router.md
-  agentkit-build-agent/
-    SKILL.md
-    templates/
-      support-agent.instructions.md
-      appointment-intake.instructions.md
-  agentkit-prompts/
-    SKILL.md
-    templates/
-      support-agent.instructions.md
-      knowledge-grounded-faq.instructions.md
-  agentkit-tools/
-    SKILL.md
-    examples/
-      lookup-order.tool.ts
-      database-write.tool.ts
-      eval-safe-external-action.tool.ts
-  agentkit-database/
-    SKILL.md
-    templates/
-      appointments.schema.sql
-      leads.schema.sql
-  agentkit-evals/
-    SKILL.md
-    templates/
-      smoke.eval.ts
-      tool-call.eval.ts
-  agentkit-deploy/
-    SKILL.md
-  agentkit-security/
-    SKILL.md
-```
-
-Channel, Knowledge, provider, and troubleshooting skills are copied into every generated capsule. Since skills are context-lazy, the main tradeoff is filesystem size, not context usage.
-
-## Handoff Changes
-
-Change generated `AGENTS.md` and `AGENTKIT.md` from:
-
-```txt
-Read AGENTKIT.md and the full docs path from npm run agentkit -- docs full.
-```
-
-To:
-
-```txt
-Start with skills/agentkit-capsule/SKILL.md.
-Use npm run agentkit -- docs llms as the docs router.
-Read npm run agentkit -- docs full only when a skill tells you the complete contract is needed.
-```
-
-Change `agentkit handoff codex|claude` so it points to:
-
-```txt
-Read these files first:
-- AGENTKIT.md
-- skills/agentkit-capsule/SKILL.md
-- the path printed by npm run agentkit -- docs llms
-```
-
-It should not include the concrete `llms-full.txt` path by default. It may mention that `llms-full.txt` exists for complete-contract checks.
-
-## CLI Packaging
-
-Keep the first version simple:
-
-```sh
-agentkit new <name> --template blank
-```
-
-The generated capsule receives the default skill pack automatically. Add `agentkit skills list/install` later only if users need to refresh or extend skill packs in existing capsules.
-
-## Acceptance Criteria
-
-The skills architecture is working when:
-
-- a new capsule contains a `skills/` directory;
-- `AGENTS.md` points to `skills/agentkit-capsule/SKILL.md`;
-- `agentkit handoff codex` points to the skill router and `docs llms`, not `llms-full.txt`;
-- ordinary prompt/tool/database tasks do not require loading `llms-full.txt`;
-- each skill has focused verification commands;
-- examples and templates live beside skills and are loaded only when needed;
-- docs remain canonical and tests still verify packaged docs sync;
-- user capsules do not include maintainer/operator skills by default.
-
-## Rollout Plan
-
-1. Add the default skill pack under `packages/agentkit/src/templates/skills` or another package-owned source directory.
-2. Update `blank`, `support`, and `dentista` templates to copy the skill pack.
-3. Update generated `AGENTS.md`, `AGENTKIT.md`, and `CLAUDE.md` to prefer skills and `docs llms`.
-4. Update `agentkit handoff` to prefer the skill router.
-5. Add tests that generated capsules contain the default skills and no longer nudge default handoff to `llms-full.txt`.
-6. Keep `agentkit docs full` available for complete-contract audits.

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.