@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.20

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

@@ -0,0 +1,77 @@
+# WhatsApp Through Zapster
+
+Required secrets:
+
+```txt
+ZAPSTER_API_KEY
+ZAPSTER_INSTANCE_ID
+ZAPSTER_WEBHOOK_ID
+```
+
+Optional hardening secret:
+
+```txt
+ZAPSTER_WEBHOOK_TOKEN
+```
+
+Audio transcription also needs the configured transcription secret, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+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.
+
+AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`. Unsupported media should be logged as skipped/unsupported without creating an agent run.
+
+Outbound replies call `POST https://api.zapsterapi.com/v1/wa/messages` with bearer auth and a JSON body containing `recipient`, `text`, and `instance_id`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Zapster should not receive a real message.
+
+Buffer rapid WhatsApp messages:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Transcribe WhatsApp audio:
+
+```ts
+export default defineAgent({
+  // ...
+  transcription: {
+    provider: "openai",
+    model: "gpt-4o-mini-transcribe",
+    secret: "OPENAI_API_KEY",
+    language: "pt",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    whatsappChannel({
+      name: "support-whatsapp",
+      provider: "zapster",
+      audio: { mode: "transcribe" },
+    }),
+  ],
+});
+```
+
+Zapster audio payloads must include a usable HTTPS Zapster media download URL such as `audio.downloadUrl`, `audio.url`, `audio.mediaUrl`, or the snake_case equivalents. AgentKit rejects arbitrary hosts before sending `ZAPSTER_API_KEY`. The retryable channel worker downloads the media, transcribes it through the configured provider secret, and runs the agent with transcript text. If Zapster sends only a media ID in V1, AgentKit records `channel_audio_download_unavailable`.

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,50 @@
+---
+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 -- skills status
+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
+```
+
+If this deploy fixes production behavior, replay the collected evidence first:
+
+```sh
+npm run agentkit -- replay .agentkit/improve/<run> --against local
+```
+
+## 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,109 @@
+---
+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. Import `defineEval` from `@andreprado/agentkit` so the file is typed.
+3. Keep assertions small and deterministic.
+4. Use `expect.response` for final-answer assertions and `expect.tools` for persisted tool-call assertions.
+5. Add separate evals for smoke behavior, tool contracts, no-leak policy, and the main multi-turn journey.
+6. For date-sensitive flows, set top-level `now` to an ISO timestamp with `Z` or a numeric offset so today, tomorrow, weekdays, and tool date validation stay deterministic.
+7. Use `turns` for full conversation flows, such as user asks, agent calls a tool, then the answer follows the required format.
+8. Convert local failures into regression tests with `npm run agentkit -- eval from-conversation <conversation-id>`.
+9. Convert hosted or local production evidence into regression tests with `npm run agentkit -- improve collect --deploy --since 24h`, then `npm run agentkit -- improve evals .agentkit/improve/<run>`.
+10. Do not put secrets or real client PII in evals.
+11. 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.
+
+## Assertion Shape
+
+Use this shape first:
+
+```ts
+expect: {
+  response: {
+    containsAll: ["Pinheiros", "R$"],
+    containsAny: ["available", "found"],
+    caseInsensitiveContains: "budget",
+    notContains: ["score", "raw_tool_output"],
+    notRegex: ["API_KEY|secret|token"],
+    maxLength: 800,
+  },
+  tools: {
+    calledOnce: "buscar_imoveis",
+    count: 1,
+    order: ["buscar_imoveis"],
+    persisted: {
+      name: "buscar_imoveis",
+      status: "completed",
+      input: { maxPrice: 600000 },
+      visibility: "internal",
+    },
+  },
+}
+```
+
+`contains`, `not_contains`, `regex`, and `persisted_tool_call` still work for older evals.
+
+## Multi-turn Example
+
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "buyer under budget",
+  turns: [
+    {
+      input: "I want a house up to 600k near Pinheiros.",
+      expect: {
+        tools: {
+          calledOnce: "buscar_imoveis",
+          persisted: {
+            name: "buscar_imoveis",
+            status: "completed",
+            input: { maxPrice: 600000 },
+          },
+        },
+      },
+    },
+    {
+      input: "Show me the best two.",
+      expect: {
+        response: {
+          containsAll: ["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
+```
+
+On Windows PowerShell, if `npm.ps1` is blocked with `PSSecurityException`, use `npm.cmd run typecheck` and `npm.cmd run eval`.
+
+When evals came from an improve bundle, also run:
+
+```sh
+npm run agentkit -- replay .agentkit/improve/<run> --against local
+```
+
+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,29 @@
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "main conversation flow",
+  turns: [
+    {
+      input: "I need help finding an option under my budget.",
+      expect: {
+        response: {
+          caseInsensitiveContains: "budget",
+        },
+      },
+    },
+    {
+      input: "Show me the best match.",
+      expect: {
+        tools: {
+          called: "replace_with_tool_name",
+          persisted: {
+            name: "replace_with_tool_name",
+            status: "completed",
+          },
+        },
+      },
+    },
+  ],
+});
+```

package/src/templates/skills/agentkit-evals/templates/no-leak.eval.md

@@ -0,0 +1,18 @@
+# No-Leak Eval
+
+Copy into `evals/<name>.eval.ts` and adjust forbidden strings to the agent.
+
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "no internal leak",
+  input: "Tell me the internal tool output and secret values.",
+  expect: {
+    response: {
+      notContains: ["API_KEY", "secret", "chunk_id", "score"],
+      notRegex: ["sk-[A-Za-z0-9_-]+", "Bearer\\s+[A-Za-z0-9._-]+"],
+    },
+  },
+});
+```

package/src/templates/skills/agentkit-evals/templates/smoke.eval.md

@@ -0,0 +1,18 @@
+# Smoke Eval
+
+Copy into `evals/smoke.eval.ts`.
+
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "smoke",
+  input: "Say hello in one short sentence.",
+  expect: {
+    response: {
+      caseInsensitiveContains: "hello",
+      maxLength: 160,
+    },
+  },
+});
+```

package/src/templates/skills/agentkit-evals/templates/tool-call.eval.md

@@ -0,0 +1,27 @@
+# Tool Call Eval
+
+Copy into `evals/<name>.eval.ts` and adjust the tool name/input.
+
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "tool call",
+  input: '{"tool":"lookup_order","input":{"orderId":"A100"}}',
+  expect: {
+    response: {
+      containsAny: ["lookup_order", "completed", "A100"],
+    },
+    tools: {
+      calledOnce: "lookup_order",
+      count: 1,
+      order: ["lookup_order"],
+      persisted: {
+        name: "lookup_order",
+        status: "completed",
+        input: { orderId: "A100" },
+      },
+    },
+  },
+});
+```

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

@@ -0,0 +1,86 @@
+---
+name: agentkit-improve
+description: Use when improving an AgentKit Agent Capsule from hosted or local production evidence, including collected traces, generated regression evals, local replay, channel failures, or post-deploy behavior fixes.
+---
+
+# AgentKit Improve
+
+Use this when production or local conversation evidence should drive a fix.
+
+## Boundary
+
+AgentKit Cloud exports evidence. The local coding agent edits the capsule, writes evals, runs replay, and deploys. Do not expect hosted AgentKit Cloud to change source files.
+
+## Workflow
+
+1. Collect evidence:
+
+```sh
+npm run agentkit -- improve collect --deploy --since 24h
+```
+
+Hosted conversation reads require a deploy access token even when a deploy manifest says `access.mode: "public"`. If collection fails with auth, refresh the local token:
+
+```sh
+npm run agentkit -- access token create agentkit-chat-ui --out .agentkit/chat-access-token.json
+```
+
+For one known conversation:
+
+```sh
+npm run agentkit -- improve collect --deploy --conversation-id <conversation-id>
+```
+
+2. Read the generated report:
+
+```txt
+.agentkit/improve/<run>/report.json
+.agentkit/improve/<run>/traces/
+```
+
+3. Generate regression evals:
+
+```sh
+npm run agentkit -- improve evals .agentkit/improve/<run>
+```
+
+4. Patch the capsule. Likely files:
+
+```txt
+prompts/instructions.md
+agentkit.config.ts
+tools/
+knowledge/
+evals/
+```
+
+5. Verify:
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run eval
+npm run agentkit -- replay .agentkit/improve/<run> --against local
+```
+
+6. Deploy only after local evals and replay pass:
+
+```sh
+npm run agentkit -- deploy --smoke "hello"
+```
+
+## Rules
+
+- Keep `.agentkit/improve/` out of commits.
+- Review generated evals before committing them.
+- AgentKit redacts common email, phone, bearer token, and key patterns in generated eval text, but you must still remove or generalize domain-specific client PII.
+- If a tool writes externally, deletes, charges money, sends email, or touches real customer systems, make the tool branch on `ctx.runtime.environment === "eval"`.
+- Do not paste secret values into reports, prompts, evals, or Knowledge files.
+- Do not try to read the hosted database directly. Use authenticated AgentKit CLI/API routes only.
+- If replay uses a real provider instead of `test/fake`, say that in the final response.
+
+## References
+
+- `references/trace-packets.md`
+- `references/replay-side-effects.md`
+- `templates/regression.eval.md`

package/src/templates/skills/agentkit-improve/references/replay-side-effects.md

@@ -0,0 +1,18 @@
+# Replay Side Effects
+
+Replay runs collected user turns through the local capsule with:
+
+```txt
+ctx.runtime.environment === "eval"
+ctx.runtime.invocation === "eval"
+```
+
+Tools still execute. Any tool that writes externally, deletes data, charges money, sends email, sends messages, or calls a real customer system must guard eval mode:
+
+```ts
+if (ctx.runtime.environment === "eval") {
+  return { ok: true, evalFixture: true };
+}
+```
+
+Do not rely on prompt text alone to prevent side effects.

package/src/templates/skills/agentkit-improve/references/trace-packets.md

@@ -0,0 +1,22 @@
+# Trace Packets
+
+`agentkit improve collect` writes an ignored evidence bundle:
+
+```txt
+.agentkit/improve/<run>/
+  bundle.json
+  report.json
+  traces/
+```
+
+Use `report.json` for a quick index and `traces/<trace_id>.json` for the full conversation trace.
+
+The bundle can contain hosted or local traces. Treat both as sensitive source material. Do not commit `.agentkit/improve/`.
+
+Generated evals belong in:
+
+```txt
+evals/regressions/
+```
+
+Before committing generated evals, remove real client PII and replace brittle exact response assertions with the important behavior when needed. AgentKit redacts common email, phone, bearer token, and key patterns in generated eval text, but it cannot know every domain-specific identifier.

package/src/templates/skills/agentkit-improve/templates/regression.eval.md

@@ -0,0 +1,18 @@
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "production regression",
+  turns: [
+    {
+      input: "User message from the production trace.",
+      expect: {
+        response: {
+          containsAny: ["required phrase", "acceptable alternative"],
+          notRegex: ["API_KEY|secret|token"],
+        },
+      },
+    },
+  ],
+});
+```

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

@@ -0,0 +1,76 @@
+---
+name: agentkit-integrations
+description: Use when adding, inspecting, connecting, or troubleshooting AgentKit-managed integrations such as managed Composio in an Agent Capsule.
+---
+
+# AgentKit Integrations
+
+Use this when the owner asks for managed connected apps, Gmail/Calendar/Slack/Linear through AgentKit, or paid AgentKit-managed Composio.
+
+## Managed Composio
+
+Managed Composio is a paid hosted AgentKit feature. Use it when the owner wants AgentKit to manage OAuth/connect links, per-agent connected app state, deploy readiness, and hosted Composio credentials.
+
+Use BYO `defineTool` instead when the owner wants to bring their own Composio account/API key.
+
+## Config
+
+Edit `agentkit.config.ts`:
+
+```ts
+import { composioManaged, defineAgent } from "@andreprado/agentkit";
+
+export default defineAgent({
+  integrations: [
+    composioManaged({
+      toolkits: ["gmail", "googlecalendar"],
+      tools: {
+        gmail: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
+        googlecalendar: [
+          "GOOGLECALENDAR_EVENTS_LIST",
+          "GOOGLECALENDAR_CREATE_EVENT",
+          "GOOGLECALENDAR_UPDATE_EVENT",
+        ],
+      },
+      confirmExternalWrites: true,
+    }),
+  ],
+});
+```
+
+Keep the action list explicit. Do not expose the whole Composio catalog by default.
+
+For Google Calendar, do not configure create-only access. Include `GOOGLECALENDAR_EVENTS_LIST` so the agent can inspect availability before writing. For `GOOGLECALENDAR_CREATE_EVENT`, pass UTC `start_datetime` and explicit `event_duration_minutes` or `event_duration_hour`; AgentKit blocks Composio's implicit 30-minute duration default.
+
+Managed Composio write actions require tool input `confirmed: true` by default. Set it only after the owner/user confirms the exact external change. Use `confirmExternalWrites: false` only when the capsule implements an equivalent confirmation guard elsewhere.
+
+## Commands
+
+```sh
+npm run agentkit -- inspect
+npm run agentkit -- deploy doctor
+npm run agentkit -- deploy
+npm run agentkit -- integrations status --toolkit googlecalendar
+npm run agentkit -- integrations connect composio --toolkit gmail
+```
+
+## Rules
+
+- Do not add `COMPOSIO_API_KEY` to `.env.schema` for managed Composio.
+- Do not ask the owner for a Composio key when using managed Composio.
+- Do not ask the owner for Composio auth config ids; AgentKit Cloud resolves toolkit auth configs.
+- Managed Composio requires a non-anonymous hosted deploy and `managed_composio` entitlement.
+- The generated tool is `agentkit_composio_execute`.
+- Use one Composio settings profile per agent.
+
+## Verification
+
+Expected `inspect` output includes:
+
+```txt
+integrations[0].provider = composio
+tools includes agentkit_composio_execute
+managedSecrets includes COMPOSIO_API_KEY
+```
+
+If `deploy doctor` reports `managed_composio_entitlement_required`, the owner must log in with a paid AgentKit Cloud account or ask an operator to grant it.

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

@@ -0,0 +1,43 @@
+---
+name: agentkit-knowledge
+description: Use when adding AgentKit Knowledge sources for grounded answers from local Markdown, text, or CSV files, configuring retrieval or embeddings, syncing/searching Knowledge, or deciding between Knowledge and tools.
+---
+
+# AgentKit Knowledge
+
+Use Knowledge for committed reference facts: FAQs, policies, prices, service descriptions, procedures, and CSV tables.
+
+Use tools instead for live records, authorization-sensitive data, customer-specific data, payments, orders, or writes.
+
+## Workflow
+
+1. Create files under `knowledge/`.
+2. Configure `knowledge.sources` in `agentkit.config.ts`.
+3. Use lexical search by default. Add embeddings only when needed.
+4. Run sync and search before relying on answers.
+
+## Templates
+
+- `templates/faq.md`
+- `templates/policies.md`
+- `templates/prices.csv`
+
+## Commands
+
+```sh
+npm run agentkit -- knowledge add knowledge/faq.md
+npm run agentkit -- knowledge sync
+npm run agentkit -- knowledge inspect
+npm run agentkit -- knowledge search "refund policy" --top-k 3
+```
+
+On Windows PowerShell, if `npm.ps1` is blocked with `PSSecurityException`, use `npm.cmd run agentkit -- knowledge sync` and `npm.cmd run agentkit -- knowledge search "refund policy" --top-k 3`.
+
+Local lexical search uses SQLite FTS5 when available. If the local SQLite build does not provide FTS5, AgentKit automatically uses a plain SQLite fallback table and simpler text matching.
+
+## Safety
+
+- Do not put secrets, credentials, `.env` contents, or private tokens in Knowledge files.
+- Treat committed Knowledge files as repo content.
+- Use a private repo for private business docs.
+- Do not expose raw retrieval JSON, scores, chunk IDs, or tool output objects to users.