@andreprado/agentkit 0.1.0-alpha.5 → 0.1.0-alpha.7

package/README.md

@@ -34,11 +34,20 @@ Once the capsule is running:
 
 ```sh
 agentkit tool <name> [--input <path-or-json>]
+agentkit knowledge add <path-or-url>
+agentkit knowledge sync
+agentkit knowledge search <query> [--top-k <number>]
+agentkit spec init --brief <text>
 agentkit db migrate
+agentkit sync run
 agentkit eval run
+agentkit eval from-conversation <conversation-id>
 agentkit conversations list
+agentkit conversations trace <conversation-id>
 ```
 
+Knowledge indexes local `.md`, `.txt`, and `.csv` sources into the capsule database and registers the internal `agentkit_search_knowledge` chat tool when `knowledge` is configured in `agentkit.config.ts`. `agentkit dev` and `agentkit chat` sync configured sources automatically; when embeddings are configured, local semantic search uses a libSQL vector sidecar. Hosted Cloudflare deploys package configured local Knowledge sources and sync them into the project Turso database automatically during `agentkit deploy`; when embeddings are configured, the deploy also creates and populates the hosted Turso vector index.
+
 ## Deploy Later
 
 ```sh

package/docs/guides/add-channel.md

@@ -54,12 +54,35 @@ export default defineAgent({
 });
 ```
 
+## Buffer Bursty Messages
+
+Use `buffer` when clients send several short messages in a row and the agent should answer once.
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Buffering is scoped to one channel conversation. AgentKit still validates and dedupes each provider webhook, then stores the messages in a short-lived channel buffer. When the quiet window expires, AgentKit creates one agent run with the buffered messages and sends one outbound reply.
+
+Use `buffer: { mode: "off" }` or omit `buffer` to process each inbound message as its own agent run.
+
 ## Safety Rules
 
 - Never put provider token values in `agentkit.config.ts`.
 - Keep local values in ignored `.env`; hosted production uses managed secrets with no readback.
 - Treat channel webhook URLs as public transport endpoints. Provider validation or the AgentKit website channel token controls authenticity.
 - Keep channels separate from tools. Channels deliver user messages; tools let the agent call external systems.
+- Keep `maxMessages` and `maxChars` bounded so one burst cannot create an oversized prompt or unexpected model spend.
 
 ## Verification
 
@@ -87,3 +110,5 @@ The provider webhook secret/token does not match the managed secret.
 
 `channel_limit_exceeded`:
 The channel daily message limit was reached. Website requests return `429`; Telegram and WhatsApp are acknowledged and skipped to avoid provider retry storms.
+
+Buffered messages stay in `buffered` delivery state until the quiet window or max wait flushes them into one queued run.

package/docs/guides/add-knowledge.md

@@ -0,0 +1,134 @@
+# Add Knowledge
+
+Knowledge is AgentKit's native retrieval layer for facts the agent should not invent: policies, prices, service details, FAQs, CSV tables, procedures, and internal reference docs.
+
+Use Knowledge when the answer should come from source files instead of the base prompt. Do not use Knowledge for secrets, credentials, or data that should only be fetched live through a tool.
+
+## Configure
+
+Create a `knowledge/` directory in the Agent Capsule and list the sources in `agentkit.config.ts`:
+
+```ts
+export default defineAgent({
+  // ...
+  knowledge: {
+    sources: [
+      "knowledge/faq.md",
+      { path: "knowledge/prices.csv", title: "Prices" },
+    ],
+    retrieval: {
+      topK: 8,
+      hybrid: false,
+    },
+  },
+});
+```
+
+Local Knowledge supports `.md`, `.markdown`, `.txt`, and `.csv` files. Markdown is chunked by headings, text is chunked by paragraphs, and CSV rows preserve column headers.
+
+The default embedding provider is `none`, which gives local lexical search without an API key. To add embeddings, configure them separately from the chat provider:
+
+```ts
+knowledge: {
+  sources: ["knowledge/faq.md"],
+  embedding: {
+    provider: "openai",
+    model: "text-embedding-3-small",
+    secret: "KNOWLEDGE_OPENAI_API_KEY",
+  },
+  retrieval: {
+    topK: 8,
+    hybrid: true,
+  },
+},
+```
+
+Then set the local secret without committing it:
+
+```sh
+printf %s "$KNOWLEDGE_OPENAI_API_KEY" | agentkit env set KNOWLEDGE_OPENAI_API_KEY --stdin
+```
+
+## Index Locally
+
+Index one source:
+
+```sh
+agentkit knowledge add knowledge/faq.md
+```
+
+Sync all configured sources:
+
+```sh
+agentkit knowledge sync
+```
+
+Inspect indexed sources:
+
+```sh
+agentkit knowledge inspect
+```
+
+Search locally:
+
+```sh
+agentkit knowledge search "refund policy" --top-k 3
+```
+
+`knowledge add` is useful for one-off local indexing. `knowledge sync` validates and indexes all configured `knowledge.sources` on demand. `agentkit dev` and `agentkit chat` also sync configured Knowledge automatically before local runs, and unchanged files are skipped by content hash.
+
+When embeddings are configured locally, AgentKit stores canonical Knowledge chunks in `.agentkit/agentkit.db` and rebuilds a local libSQL vector sidecar at `.agentkit/agentkit.vectors.db`. Local semantic search uses the sidecar's native `libsql_vector_idx` path and falls back to stored JSON embeddings if the native vector path is unavailable.
+
+## Agent Behavior
+
+When `knowledge` is configured, AgentKit automatically registers the internal tool `agentkit_search_knowledge` during chat runs and appends a prompt policy. The policy tells the agent to search before answering business-specific factual questions and not to expose raw retrieval JSON, scores, or chunk IDs.
+
+With the deterministic `test/fake` provider, verify the internal tool directly:
+
+```sh
+agentkit chat --message '{"tool":"agentkit_search_knowledge","input":{"query":"refund policy","topK":1}}'
+```
+
+Expected output:
+
+```txt
+Tool agentkit_search_knowledge: completed
+```
+
+The retrieved chunks are persisted as internal tool output in local SQLite for evals and inspection, but they are not shown directly to the user.
+
+## Hosted Deploy
+
+Cloudflare Knowledge deploys require AgentKit-managed Turso storage:
+
+```ts
+storage: {
+  driver: "agentkit",
+  database: {
+    driver: "turso",
+    schema: "./schema.sql",
+  },
+},
+```
+
+`agentkit deploy doctor` and `agentkit build --target cloudflare` fail with an actionable error when Knowledge is configured without Turso. The Cloudflare artifact includes the Knowledge manifest, required embedding secret names, internal Knowledge schema, local source file contents, prompt policy, and hosted `agentkit_search_knowledge` runtime.
+
+During `agentkit deploy`, AgentKit Cloud provisions or resolves the project Turso database, applies the Knowledge schema, chunks every packaged local source, creates embeddings when an embedding provider is configured, and writes sources, chunks, embedding metadata, FTS rows, and a native Turso `libsql_vector_idx` index into Turso before publishing the Worker. Removed configured sources are deleted from the hosted Knowledge tables during sync.
+
+Local `agentkit knowledge add`, `agentkit knowledge sync`, `agentkit dev`, and `agentkit chat` index configured Knowledge into the local SQLite database and local libSQL vector sidecar. Hosted deploy syncs configured local Knowledge sources automatically from the deploy artifact so embedding secrets stay server-side and private source material does not move into client code. Hosted semantic search uses Turso native vector search when embeddings are configured and falls back to stored JSON embeddings if the native vector path is unavailable.
+
+## Safety Rules
+
+- Do not put API keys, passwords, private tokens, `.env` contents, or credential exports in Knowledge files.
+- Treat committed Knowledge files as repository content. Use a private repo for private business docs.
+- Use tools for live customer records, payments, orders, or anything requiring authorization checks.
+- Use explicit `title` fields for CSVs or ambiguous files so search results have useful citations.
+- Use `agentkit knowledge sync` to validate source changes explicitly; local `agentkit dev` and `agentkit chat` also sync configured sources automatically.
+
+## Troubleshooting
+
+- `No knowledge.sources are configured`: add `knowledge.sources` to `agentkit.config.ts` or use `agentkit knowledge add <path>`.
+- `Knowledge source paths must stay inside the Agent Capsule`: move the source under the capsule root, usually `knowledge/`.
+- `Local Knowledge currently supports .md, .txt, and .csv files`: convert the source or add a tool for unsupported formats.
+- `Knowledge embeddings require missing secret`: set the env var named by `knowledge.embedding.secret`.
+- Hosted build says Turso is required: add `storage.database.driver: "turso"` before deploying Knowledge.

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

@@ -0,0 +1,471 @@
+# 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;
+- 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-production-handoff.md

@@ -81,6 +81,7 @@ Zapster smoke requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGEN
 - Invalid Telegram/Zapster signature returns `401` and creates 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.
 
@@ -94,6 +95,7 @@ Zapster smoke requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGEN
 ## 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.