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

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

@@ -23,6 +23,8 @@ 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 test-audio support-telegram --fixture voice-note
+agentkit transcribe smoke --provider groq
 agentkit channels deliveries list support-telegram
 ```
 
@@ -67,4 +69,4 @@ export default defineAgent({
 });
 ```
 
-AgentKit validates the Telegram webhook, normalizes `voice` and `audio` payloads, enqueues an audio job, then the retryable channel worker calls Telegram `getFile`, downloads the media with `TELEGRAM_BOT_TOKEN`, sends the bytes to the configured transcription provider, and runs the agent with transcript text. Telegram voice notes are usually OGG/Opus; use Groq in V1 for that path.
+AgentKit validates the Telegram webhook, normalizes `voice` and `audio` payloads, enqueues an audio job, then the retryable channel worker calls Telegram `getFile`, downloads the media with `TELEGRAM_BOT_TOKEN`, sends the bytes to the configured transcription provider, and runs the agent with transcript text. Telegram voice notes are usually OGG/Opus; use Groq in V1 for that path. `test-audio` validates the audio channel ingress path; `transcribe smoke` validates the transcription provider separately.

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

@@ -18,6 +18,7 @@ Use this when the owner asks to prepare, test, or run hosted deploy.
 
 ```sh
 npm run typecheck
+npm run agentkit -- skills status
 npm run agentkit -- inspect
 npm run agentkit -- db migrate
 npm run chat -- --message "hello"
@@ -41,4 +42,3 @@ 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-integrations/SKILL.md

@@ -0,0 +1,75 @@
+---
+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.
+- 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-troubleshooting/SKILL.md

@@ -18,6 +18,7 @@ Use this when something fails.
 
 ```sh
 npm run agentkit -- inspect
+npm run agentkit -- skills status
 npm run typecheck
 npm run agentkit -- env list
 git status --short
@@ -48,5 +49,5 @@ npm run agentkit -- deploy doctor
 - provider not chosen: stay on `test/fake` or ask the owner;
 - schema missing: run `db migrate` and check `schema.sql`;
 - tool validation failed: check `inputSchema` and `outputSchema`;
-- channel secret missing: set hosted managed secret, not source files.
-
+- channel secret missing: set hosted managed secret, not source files;
+- local AgentKit skills are stale: run `npm run agentkit -- skills sync`.

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.