@andreprado/agentkit 0.1.0-alpha.10

package/src/templates/index.ts

@@ -0,0 +1,33 @@
+import { blankTemplate } from "./blank";
+import { dentistaTemplate } from "./dentista";
+import { supportTemplate } from "./support";
+
+export type TemplateFile = {
+  path: string;
+  contents: string;
+};
+
+export type AgentTemplate = {
+  name: string;
+  files(projectName: string, context?: AgentTemplateContext): TemplateFile[];
+};
+
+export type AgentTemplateContext = {
+  agentkitDependency?: string;
+};
+
+const templates = new Map<string, AgentTemplate>([
+  [blankTemplate.name, blankTemplate],
+  [dentistaTemplate.name, dentistaTemplate],
+  [supportTemplate.name, supportTemplate],
+]);
+
+export function getTemplate(name: string): AgentTemplate {
+  const template = templates.get(name);
+
+  if (!template) {
+    throw new Error(`Unknown template "${name}". Available templates: ${Array.from(templates.keys()).join(", ")}`);
+  }
+
+  return template;
+}

package/src/templates/skills/agentkit-build-agent/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: agentkit-build-agent
+description: Use when the owner gives a natural-language brief for a new or changed AgentKit agent and expects the coding agent to turn it into a working local capsule with prompts, tools, schema, evals, and verification.
+---
+
+# Build An AgentKit Agent
+
+Use this when the owner asks for an agent in plain language.
+
+## Workflow
+
+1. Read `agentkit.config.ts`, `prompts/instructions.md`, `schema.sql`, `evals/`, and existing `tools/`.
+2. If `AGENT_SPEC.md` does not exist, create it from the owner's plain-language request with `npm run agentkit -- spec init --brief "<owner request>"`. If it exists, update it directly before changing behavior.
+3. Infer the first useful local version from the owner's brief and the spec. Do not ask the owner to fill a form.
+4. Edit `prompts/instructions.md` for behavior, boundaries, intake questions, escalation rules, and tool-use policy.
+5. Add tools only when the agent needs action, live data, authorization-sensitive data, or durable writes.
+6. Add database tables to `schema.sql` or ordered `migrations/*.sql` when the agent owns records.
+7. Add `sync.ts` and `seed.sql` with `npm run agentkit -- sync init` when the agent depends on external catalogs or recurring imports.
+8. Add or update evals for the main flow. Prefer multi-turn `turns` evals for real conversations.
+9. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+
+## Templates
+
+Use these only when they match the brief:
+
+- `templates/support-agent.instructions.md`
+- `templates/appointment-intake.instructions.md`
+- `templates/sales-qualifier.instructions.md`
+
+For prompt-only work, use `skills/agentkit-prompts/SKILL.md`.
+For database-backed tools, use `skills/agentkit-database/SKILL.md`.
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+npm run eval
+npm run agentkit -- spec check
+```
+
+If a tool was added:
+
+```sh
+npm run agentkit -- tool <tool_name> --input '<json>'
+```
+
+## Final Response
+
+Summarize the files changed, assumptions made, verification results, and whether the behavior was tested with `test/fake` or a real provider selected by the owner.

package/src/templates/skills/agentkit-build-agent/templates/appointment-intake.instructions.md

@@ -0,0 +1,20 @@
+You are an appointment and intake agent.
+
+Goal:
+- Collect the information needed to understand the request.
+- Offer available times only after checking availability through tools.
+- Confirm the exact date, time, name, and contact details before saving.
+
+Required intake:
+- Full name
+- Contact method
+- Reason for visit
+- Preferred date or time window
+- Any urgency or special constraints
+
+Rules:
+- Do not diagnose, promise outcomes, or provide emergency guidance beyond directing urgent cases to appropriate human or emergency support.
+- Do not create, change, or cancel an appointment without explicit user confirmation.
+- Do not invent availability.
+- Use the scheduling tools for availability and writes.
+

package/src/templates/skills/agentkit-build-agent/templates/sales-qualifier.instructions.md

@@ -0,0 +1,17 @@
+You are a sales qualification agent.
+
+Goal:
+- Understand the user's current situation, urgency, budget range, authority, and desired outcome.
+- Identify whether the lead is a fit for the configured offer.
+- Capture structured lead details through tools when available.
+
+Behavior:
+- Ask one focused question at a time.
+- Avoid pressure and exaggerated claims.
+- Be clear about what is known, unknown, and next.
+- Escalate to a human when the user asks for pricing exceptions, legal terms, procurement details, or custom commitments.
+
+Rules:
+- Do not invent pricing, discounts, case studies, or availability.
+- Do not expose internal lead scores or qualification labels.
+

package/src/templates/skills/agentkit-build-agent/templates/support-agent.instructions.md

@@ -0,0 +1,16 @@
+You are a focused support agent.
+
+Help users resolve the current issue clearly and efficiently.
+
+Behavior:
+- Ask for the minimum missing context needed to help.
+- Use tools when order, account, booking, or case status is needed.
+- Do not invent status, policy, price, or availability.
+- Explain next steps in plain language.
+- Escalate when the request involves billing disputes, safety, legal issues, account ownership, or anything outside the configured tools.
+
+Boundaries:
+- Do not claim to have changed anything unless a tool confirms it.
+- Do not expose internal tool output, IDs, scores, secrets, or logs.
+- If a tool fails, say what could not be verified and ask for a safe next step.
+

package/src/templates/skills/agentkit-capsule/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: agentkit-capsule
+description: Use when working inside an AgentKit Agent Capsule, especially after detecting agentkit.config.ts or when the owner asks to build, change, test, or deploy an AgentKit agent. Routes to task-specific AgentKit skills while avoiding loading the full docs by default.
+---
+
+# AgentKit Capsule
+
+Use this first inside an AgentKit Agent Capsule.
+
+## Start
+
+1. Treat the directory containing `agentkit.config.ts` as the capsule root.
+2. Read `AGENTS.md` or `AGENTKIT.md` for capsule-specific rules.
+3. Run `npm run agentkit -- docs llms` for the lightweight docs router.
+4. Pick one task skill. Do not load `llms-full.txt` unless a task skill or ambiguous framework behavior requires the complete contract.
+
+## Task Routing
+
+- Build or reshape the agent from the owner's brief: `skills/agentkit-build-agent/SKILL.md`
+- Edit prompts: `skills/agentkit-prompts/SKILL.md`
+- Add actions or external data: `skills/agentkit-tools/SKILL.md`
+- Add database tables or database-backed tools: `skills/agentkit-database/SKILL.md`
+- Add docs, FAQs, prices, policies, or CSV facts: `skills/agentkit-knowledge/SKILL.md`
+- Switch from `test/fake` to a real model provider: `skills/agentkit-provider/SKILL.md`
+- Add or run evals: `skills/agentkit-evals/SKILL.md`
+- Prepare hosted deploy: `skills/agentkit-deploy/SKILL.md`
+- Work with secrets, external APIs, public access, channels, or real data: `skills/agentkit-security/SKILL.md`
+- Add or debug website, Telegram, or WhatsApp channels: `skills/agentkit-channels/SKILL.md`
+- Investigate command failures: `skills/agentkit-troubleshooting/SKILL.md`
+
+For a compact docs map, read `references/docs-router.md`.
+
+## Default Checks
+
+Run these before finishing ordinary capsule work:
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+```
+
+If you add a tool, also run:
+
+```sh
+npm run agentkit -- tool <tool_name> --input '{}'
+```
+
+If you change behavior, add or update an eval and run:
+
+```sh
+npm run eval
+```
+
+## Rules
+
+- Keep `.env`, `.agentkit/`, and `node_modules/` out of commits.
+- Keep secret names in `.env.schema`; keep secret values in ignored `.env` or hosted managed secrets.
+- Keep the first useful version runnable with `test/fake` unless the owner explicitly chooses a real provider.
+- Ask follow-up questions only when missing information blocks a safe local implementation.
+- Tell the owner when testing used `test/fake` instead of a real provider.
+

package/src/templates/skills/agentkit-capsule/references/docs-router.md

@@ -0,0 +1,15 @@
+# AgentKit Docs Router
+
+Prefer the narrowest source that covers the task.
+
+- Capsule creation and scaffold verification: `docs/guides/create-agent.md`
+- Tools, schemas, secrets, and direct tool tests: `docs/guides/add-tool.md`
+- Knowledge sources, indexing, search, and hosted sync: `docs/guides/add-knowledge.md`
+- Evals and deterministic side-effect guards: `docs/guides/run-evals.md`
+- Real provider setup: `docs/guides/use-provider.md`
+- Deploy readiness, managed secrets, smoke checks, hosted UI: `docs/guides/prepare-deploy.md`
+- Channels: `docs/guides/add-channel.md`, `connect-telegram.md`, `connect-whatsapp-zapster.md`, `debug-channel.md`
+- Security: `docs/guides/security-rules.md`
+
+Use `npm run agentkit -- docs full` only for a complete-contract audit, framework internals, or a behavior not covered by the task guide.
+

package/src/templates/skills/agentkit-channels/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: agentkit-channels
+description: Use when adding, connecting, testing, buffering, or debugging AgentKit website, Telegram, or WhatsApp channels, including channel config helpers, provider secrets, webhook setup, channel tests, delivery logs, and burst-message buffers.
+---
+
+# AgentKit Channels
+
+Channels receive user messages. Tools let the agent call external systems. Keep them separate.
+
+## Workflow
+
+1. Add channel helpers in `agentkit.config.ts`.
+2. Keep `runtime: "edge"` and `storage.driver: "agentkit"`.
+3. Deploy before hosted channel creation.
+4. Configure provider secrets as managed secrets.
+5. Connect channel resources through the CLI.
+6. Test, doctor, and inspect delivery logs.
+
+## Buffering
+
+Enable `buffer.mode: "debounce"` 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,
+  },
+})
+```
+
+Buffered deliveries show `buffered` until AgentKit flushes the conversation buffer into one queued run.
+
+## Commands
+
+```sh
+npm run agentkit -- inspect
+npm run agentkit -- deploy
+npm run agentkit -- channels list
+npm run agentkit -- channels add website website-chat
+npm run agentkit -- channels connect telegram support-telegram
+npm run agentkit -- channels add whatsapp support-whatsapp --provider zapster
+npm run agentkit -- channels doctor support-telegram
+npm run agentkit -- channels test support-telegram --message "hello"
+npm run agentkit -- channels deliveries list support-telegram
+```
+
+## References
+
+- `references/telegram.md`
+- `references/whatsapp-zapster.md`
+- `references/channel-buffering.md`
+- `references/channel-debugging.md`
+
+## Safety
+
+Do not paste provider tokens into code, docs, fixtures, prompts, evals, or delivery logs. Webhook URLs are public transport endpoints; authenticity comes from provider validation or channel tokens.

package/src/templates/skills/agentkit-channels/references/channel-buffering.md

@@ -0,0 +1,58 @@
+# Channel Buffering
+
+Use buffering when a client sends several messages in a burst and the agent should answer once.
+
+Config:
+
+```ts
+telegramChannel({
+  name: "support-telegram",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 1500,
+    maxWaitMs: 8000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Behavior:
+
+- Buffer scope is one channel conversation.
+- Provider validation and dedupe still run per webhook event.
+- `quietWindowMs` flushes after the client stops sending messages.
+- `maxWaitMs` guarantees a reply even if messages keep arriving.
+- `maxMessages` and `maxChars` cap prompt size and cost.
+- Omit `buffer` or set `buffer: { mode: "off" }` to run the agent once per inbound message.
+
+Debug:
+
+```sh
+agentkit channels deliveries list <name>
+agentkit channels deliveries show <delivery-id>
+```
+
+Expected delivery states:
+
+```txt
+buffered
+queued
+running
+agent_completed
+outbound_sent
+```

package/src/templates/skills/agentkit-channels/references/channel-debugging.md

@@ -0,0 +1,41 @@
+# Channel Debugging
+
+Start with:
+
+```sh
+agentkit channels list
+agentkit channels status <name>
+agentkit channels doctor <name>
+agentkit channels test <name> --message "hello"
+agentkit channels deliveries list <name> --since 24h
+agentkit channels deliveries show <delivery-id>
+```
+
+Common states:
+
+```txt
+webhook_received
+validated
+duplicate
+buffered
+queued
+running
+agent_completed
+outbound_sent
+delivered
+provider_failed
+synthetic_expected_failure
+dead_lettered
+skipped
+```
+
+Common errors:
+
+- `channel_not_found`: webhook URL points to an unknown channel.
+- `channel_secret_missing`: required hosted secret is not set.
+- `channel_signature_invalid`: webhook secret, token, or origin header mismatch.
+- `channel_payload_invalid`: malformed or unsupported provider payload.
+- `channel_event_duplicate`: provider retry; do not create a second run.
+- `channel_limit_exceeded`: backpressure skipped the message.
+- `synthetic_expected_failure`: a synthetic test reached AgentKit, but the provider correctly rejected a fake test recipient.
+- `buffered` delivery state: message is waiting for the channel quiet window or max wait before one coalesced agent run is queued.

package/src/templates/skills/agentkit-channels/references/telegram.md

@@ -0,0 +1,38 @@
+# Telegram Channel
+
+Required secrets:
+
+```txt
+TELEGRAM_BOT_TOKEN
+TELEGRAM_WEBHOOK_SECRET
+```
+
+Commands:
+
+```sh
+agentkit deploy
+agentkit secret set TELEGRAM_BOT_TOKEN --stdin
+agentkit secret set TELEGRAM_WEBHOOK_SECRET --stdin
+agentkit channels connect telegram support-telegram
+agentkit channels doctor support-telegram
+agentkit channels status support-telegram
+agentkit channels test support-telegram --message "hello"
+agentkit channels deliveries list support-telegram
+```
+
+`connect` creates or reuses the hosted channel, validates managed secrets, calls Telegram `setWebhook`, confirms `getWebhookInfo`, runs a synthetic smoke, and prints the human Telegram steps. Use `setup --apply` only when you need to repeat webhook registration without running smoke.
+
+Buffer rapid Telegram messages:
+
+```ts
+telegramChannel({
+  name: "support-telegram",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 1500,
+    maxWaitMs: 8000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```

package/src/templates/skills/agentkit-channels/references/whatsapp-zapster.md

@@ -0,0 +1,44 @@
+# WhatsApp Through Zapster
+
+Required secrets:
+
+```txt
+ZAPSTER_API_KEY
+ZAPSTER_INSTANCE_ID
+ZAPSTER_WEBHOOK_ID
+```
+
+Optional hardening secret:
+
+```txt
+ZAPSTER_WEBHOOK_TOKEN
+```
+
+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
+```
+
+Paste the stable AgentKit webhook URL into Zapster settings. If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, append `?token=<ZAPSTER_WEBHOOK_TOKEN>` to the Zapster webhook URL. Keep phone numbers redacted in logs by default.
+
+Buffer rapid WhatsApp messages:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```

package/src/templates/skills/agentkit-database/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: agentkit-database
+description: Use when adding AgentKit-managed database tables, editing schema.sql, writing database-backed tools, seeding local data, or verifying local/hosted storage compatibility through ctx.db.
+---
+
+# AgentKit Database
+
+Use this when a capsule owns durable application records.
+
+## Rules
+
+- Put the first idempotent bootstrap schema in `schema.sql`.
+- For production-shaped changes, prefer ordered `migrations/*.sql` files such as `migrations/0001_initial.sql`.
+- Keep `schema.sql` idempotent with `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive changes.
+- Keep deploy-ready capsules on `storage.driver: "agentkit"`.
+- Use `ctx.db` inside tools. `ctx.database` and `ctx.storage.sql` are aliases.
+- Do not import SQLite, Turso, or other database drivers from tools.
+- Do not edit `.agentkit/agentkit.db` by hand.
+- For external catalogs, run `npm run agentkit -- sync init`, then implement `sync.ts` and keep local fixtures in `seed.sql`.
+
+## Templates
+
+- `templates/appointments.schema.sql`
+- `templates/leads.schema.sql`
+
+## Commands
+
+```sh
+npm run agentkit -- db migrate
+npm run agentkit -- db seed --file seed.sql
+npm run agentkit -- sync init
+npm run agentkit -- sync run
+npm run agentkit -- db shell
+npm run agentkit -- db reset --yes
+```
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- db migrate
+npm run agentkit -- tool <tool_name> --input '<json>'
+```
+
+Hosted deploy applies AgentKit-managed storage internally. The user should not create hosted databases or buckets by hand.

package/src/templates/skills/agentkit-database/templates/appointments.schema.sql

@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS appointments (
+  id TEXT PRIMARY KEY,
+  client_name TEXT NOT NULL,
+  contact TEXT NOT NULL,
+  starts_at TEXT NOT NULL,
+  notes TEXT,
+  status TEXT NOT NULL DEFAULT 'scheduled',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (starts_at)
+);
+
+CREATE INDEX IF NOT EXISTS appointments_contact_idx
+ON appointments (contact);
+

package/src/templates/skills/agentkit-database/templates/leads.schema.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS leads (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT,
+  phone TEXT,
+  status TEXT NOT NULL DEFAULT 'new',
+  notes TEXT,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS leads_status_idx
+ON leads (status);
+
+CREATE INDEX IF NOT EXISTS leads_email_idx
+ON leads (email);
+

package/src/templates/skills/agentkit-deploy/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: agentkit-deploy
+description: Use when preparing or running AgentKit hosted deploys, deploy readiness checks, managed secrets, deploy smoke tests, hosted chat UI checks, access tokens, or production handoff.
+---
+
+# AgentKit Deploy
+
+Use this when the owner asks to prepare, test, or run hosted deploy.
+
+## Rules
+
+- The user should not choose hosting infrastructure. AgentKit owns target routing.
+- Keep production secret values out of the capsule.
+- Use hosted managed secrets, not committed `.env`.
+- Run readiness checks before saying deploy-ready.
+
+## Local Readiness
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run agentkit -- db migrate
+npm run chat -- --message "hello"
+npm run agentkit -- deploy --dry-run
+npm run agentkit -- deploy doctor
+```
+
+## Hosted Flow
+
+```sh
+npm run agentkit -- login --token agk_user_...
+npm run agentkit -- secret sync --from-local
+npm run agentkit -- secret list
+npm run agentkit -- deploy --smoke "hello"
+npm run agentkit -- deploy status
+npm run agentkit -- chat-ui --deploy
+```
+
+Open the printed `Chat:` URL and report it to the owner.
+
+## Production Handoff
+
+Report changed files, required env/secret names, database schema changes, deploy order, smoke checks, rollback concerns, and whether the provider was still `test/fake`.
+

package/src/templates/skills/agentkit-evals/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: agentkit-evals
+description: Use when adding, editing, or running AgentKit eval files, including smoke evals, response assertions, persisted tool call assertions, no-leak checks, and eval-safe handling for external side effects.
+---
+
+# AgentKit Evals
+
+Use evals after chat works and before claiming behavior is stable.
+
+## Workflow
+
+1. Create or edit `evals/<name>.eval.ts`.
+2. Keep assertions small and deterministic.
+3. Use `turns` for full conversation flows, such as user asks, agent calls a tool, then the answer follows the required format.
+4. Use `persisted_tool_call` for tool behavior stored in local SQLite.
+5. Convert real failures into regression tests with `npm run agentkit -- eval from-conversation <conversation-id>`.
+6. Do not put secrets or real client PII in evals.
+7. For tools that write externally, delete, charge money, send email, or call real customer systems, branch on `ctx.runtime.environment === "eval"` inside the registered tool.
+
+## Multi-turn Example
+
+```ts
+export default {
+  name: "buyer under budget",
+  turns: [
+    {
+      input: "I want a house up to 600k near Pinheiros.",
+      expect: {
+        persisted_tool_call: {
+          name: "buscar_imoveis",
+          status: "completed",
+          input: { maxPrice: 600000 },
+        },
+      },
+    },
+    {
+      input: "Show me the best two.",
+      expect: {
+        contains: ["R$", "Pinheiros"],
+      },
+    },
+  ],
+};
+```
+
+## Templates
+
+- `templates/smoke.eval.md`
+- `templates/tool-call.eval.md`
+- `templates/multi-turn.eval.md`
+- `templates/no-leak.eval.md`
+
+## Verification
+
+```sh
+npm run typecheck
+npm run eval
+```
+
+If eval output changes after switching providers, keep deterministic smoke evals on `test/fake` and add provider-specific evals separately.

package/src/templates/skills/agentkit-evals/templates/multi-turn.eval.md

@@ -0,0 +1,22 @@
+```ts
+export default {
+  name: "main conversation flow",
+  turns: [
+    {
+      input: "I need help finding an option under my budget.",
+      expect: {
+        contains: "budget",
+      },
+    },
+    {
+      input: "Show me the best match.",
+      expect: {
+        persisted_tool_call: {
+          name: "replace_with_tool_name",
+          status: "completed",
+        },
+      },
+    },
+  ],
+};
+```