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

package/README.md

@@ -37,6 +37,8 @@ agentkit tool <name> [--input <path-or-json>]
 agentkit knowledge add <path-or-url>
 agentkit knowledge sync
 agentkit knowledge search <query> [--top-k <number>]
+agentkit integrations status
+agentkit integrations connect composio --toolkit gmail
 agentkit spec init --brief <text>
 agentkit db migrate
 agentkit sync run
@@ -50,18 +52,24 @@ Knowledge indexes local `.md`, `.txt`, and `.csv` sources into the capsule datab
 
 Every chat run receives dynamic runtime date context: current ISO timestamp, local date, weekday, local date/time, and timezone. Set `timeZone` in `agentkit.config.ts` for scheduling agents so relative dates like "today" and "next Friday" resolve in the right business/user timezone.
 
+AgentKit-managed Composio is a paid hosted integration layer for per-agent connected apps. Configure it with `composioManaged({...})`, deploy with a `managed_composio` entitlement, then use `agentkit integrations connect composio --toolkit <slug>` to create hosted Connect Links. BYO Composio remains available through normal `defineTool` wrappers.
+
 ## Deploy Later
 
 ```sh
 agentkit login --token <token>
 agentkit deploy doctor
+agentkit skills status
 agentkit secret set OPENAI_API_KEY --from-local-env
 agentkit deploy
 agentkit deploy status
+agentkit channels test support-telegram --message "hello"
+agentkit transcribe smoke --provider groq
 agentkit chat-ui --deploy
 ```
 
 Production secrets are managed secrets, not committed `.env` values.
+After upgrading AgentKit in an existing capsule, run `agentkit skills status` and `agentkit skills sync` if local agent-facing skills are stale.
 Private hosted deploys automatically store a local chat/UI deploy access token at `.agentkit/chat-access-token.json`. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy without exposing that token to browser code.
 
 The npm package contains the public CLI/runtime/client surface only. AgentKit Cloud's control-plane server, operator commands, Postgres store, and Cloudflare/Turso/R2 publisher live in the private repo workspace and are not part of the published package.

package/docs/guides/add-channel.md

@@ -87,6 +87,62 @@ agentkit channels buffers clear support-whatsapp <conversation-id>
 agentkit channels buffers retry support-whatsapp <conversation-id>
 ```
 
+## Auto Transcribe Audio
+
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on each channel that should accept voice notes or audio files.
+
+```ts
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "openai", model: "gpt-5.4-mini" },
+  instructions: "./prompts/instructions.md",
+  transcription: {
+    provider: "groq",
+    model: "whisper-large-v3-turbo",
+    secret: "GROQ_API_KEY",
+    language: "pt",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    telegramChannel({
+      name: "support-telegram",
+      audio: { mode: "transcribe" },
+    }),
+    whatsappChannel({
+      name: "support-whatsapp",
+      provider: "zapster",
+      audio: { mode: "transcribe" },
+    }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+Supported transcription providers in V1:
+
+| Provider | Default secret | Supported models |
+| --- | --- | --- |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o-mini-transcribe`, `gpt-4o-transcribe`, `whisper-1` |
+| `groq` | `GROQ_API_KEY` | `whisper-large-v3-turbo`, `whisper-large-v3`, `distil-whisper-large-v3-en` |
+
+Audio transcription is paid by the capsule owner because AgentKit only passes through the configured provider secret. Hosted channel creation automatically requires the transcription secret when a channel enables `audio.mode: "transcribe"`.
+
+Processing order:
+
+1. Provider webhook is validated and deduped.
+2. Channel adapter normalizes the audio metadata.
+3. AgentKit records `audio_received` and enqueues a channel job before acknowledging the webhook.
+4. The retryable channel worker downloads the audio using the channel provider secret.
+5. The transcription adapter sends the file to the configured transcription provider.
+6. The agent receives a text message containing the transcript.
+
+V1 keeps the raw audio in memory for the request path and delivery metadata only records redacted status/error fields. `rawAudioTtlSeconds` is part of the manifest contract for future object-storage retention, but V1 does not persist raw audio by default.
+
 ## Safety Rules
 
 - Never put provider token values in `agentkit.config.ts`.
@@ -94,6 +150,7 @@ agentkit channels buffers retry support-whatsapp <conversation-id>
 - 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.
+- Keep `audio.limits` bounded so one voice note cannot create unexpected transcription spend.
 
 ## Verification
 
@@ -103,6 +160,8 @@ bun test
 agentkit inspect
 agentkit channels list
 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
 agentkit channels buffers list support-telegram
 ```
@@ -124,4 +183,10 @@ The provider webhook secret, token, or origin header does not match the managed
 `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.
 
+`transcription_secret_missing`:
+Set the managed transcription secret declared by `agentkit inspect`, for example `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+`transcription_audio_format_unsupported`:
+The channel delivered an audio format the configured transcription provider does not accept. Telegram voice notes are OGG/Opus and work with Groq in V1; OpenAI accepts MP3, MP4, MPEG, MPGA, M4A, WAV, and WEBM in the AgentKit adapter.
+
 Buffered messages stay in `buffered` delivery state until the quiet window or max wait flushes them into one queued run.

package/docs/guides/add-managed-composio.md

@@ -0,0 +1,137 @@
+# Add Managed Composio
+
+## Goal
+
+Enable AgentKit-managed Composio for one deployed agent so the agent can use explicitly allowed external app actions without the user owning Composio credentials.
+
+Use BYO `defineTool` wrappers instead when the user wants to use their own Composio account/API key for free.
+
+## Contract
+
+Managed Composio is paid hosted AgentKit infrastructure:
+
+- It works per agent/project, not per client.
+- It requires an AgentKit Cloud account with `managed_composio`.
+- AgentKit Cloud injects `COMPOSIO_API_KEY`; do not put it in `.env`, `.env.schema`, or `agentkit.config.ts`.
+- AgentKit Cloud assigns the deployed Composio `user_id` from the account, project, agent, and integration name. The local inspect/build id is only a preview.
+- The agent gets one generated tool, `agentkit_composio_execute`, only when explicit Composio action slugs are configured.
+- Anonymous deploys cannot use managed Composio.
+
+## Minimal Config
+
+Edit `agentkit.config.ts`:
+
+```ts
+import { composioManaged, defineAgent } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "acme-receptionist",
+  runtime: "edge",
+  provider: {
+    name: "test",
+    model: "fake",
+  },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  integrations: [
+    composioManaged({
+      toolkits: ["gmail", "googlecalendar"],
+      tools: {
+        gmail: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
+        googlecalendar: ["GOOGLECALENDAR_CREATE_EVENT"],
+      },
+    }),
+  ],
+  access: {
+    mode: "private",
+  },
+  storage: {
+    driver: "agentkit",
+    database: {
+      driver: "turso",
+    },
+  },
+});
+```
+
+## Deploy
+
+```sh
+agentkit login --token agk_user_...
+agentkit deploy doctor
+agentkit deploy
+agentkit integrations status
+```
+
+Expected readiness:
+
+- `cloudflare_deploy_alpha` is active.
+- `managed_composio` is active.
+- `COMPOSIO_API_KEY` appears as an AgentKit-managed secret, not a user-managed hosted secret.
+
+## Connect Apps
+
+After deploy, create a hosted Composio Connect Link:
+
+```sh
+agentkit integrations connect composio --toolkit gmail
+agentkit integrations connect composio --toolkit googlecalendar
+```
+
+AgentKit prints a URL. Send that URL to the person who owns the app account.
+
+If the deploy has only one toolkit, `--toolkit` can be omitted.
+
+## Operator Setup
+
+Trusted AgentKit Cloud operators grant access and configure Composio auth configs:
+
+```sh
+npm run agentkit:operator -- accounts grant user@example.com --managed-composio
+```
+
+Required control-plane environment:
+
+```txt
+AGENTKIT_SECRET_COMPOSIO_API_KEY=<project API key>
+AGENTKIT_COMPOSIO_AUTH_CONFIG_GMAIL=<auth config id>
+AGENTKIT_COMPOSIO_AUTH_CONFIG_GOOGLECALENDAR=<auth config id>
+```
+
+Use one `AGENTKIT_COMPOSIO_AUTH_CONFIG_<TOOLKIT>` value per toolkit slug, uppercased with non-alphanumeric characters converted to `_`.
+
+## Verification
+
+```sh
+agentkit inspect
+agentkit build --target cloudflare
+agentkit deploy doctor
+agentkit integrations status
+```
+
+Expected:
+
+- `inspect.integrations[0].provider` is `composio`.
+- `inspect.tools` includes `agentkit_composio_execute` when allowed actions are configured.
+- Build manifest includes `integrations`.
+- Build manifest includes `COMPOSIO_API_KEY`.
+- `deploy doctor` does not ask the user to set `COMPOSIO_API_KEY`.
+
+## Troubleshooting
+
+`managed_composio_entitlement_required`:
+
+Log in with a paid AgentKit Cloud account that has `managed_composio`.
+
+`managed_composio_auth_config_missing`:
+
+An operator must set `AGENTKIT_COMPOSIO_AUTH_CONFIG_<TOOLKIT>` on the control plane.
+
+`managed_composio_not_configured`:
+
+An operator must set `AGENTKIT_SECRET_COMPOSIO_API_KEY` on the control plane.
+
+`integration_toolkit_required`:
+
+The deploy has multiple configured toolkits. Re-run connect with `--toolkit <slug>`.

package/docs/guides/channel-security.md

@@ -15,6 +15,7 @@ agentkit inspect
 agentkit channels status <name>
 agentkit channels deliveries show <delivery-id>
 bun test packages/agentkit/src/runtime/channels/adapters.test.ts
+bun test packages/agentkit/src/runtime/transcription.test.ts
 bun test packages/agentkit/src/runtime/deploy.test.ts
 ```
 
@@ -41,9 +42,12 @@ Zapster smoke also requires `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `AGENT
 - Validate provider authenticity when the provider supports it.
 - Do not store channel plumbing in the user's Turso database.
 - Do not store raw webhook bodies in delivery records; store a SHA-256 hash.
+- Do not store raw audio in delivery records. V1 audio transcription downloads provider media into memory and stores only redacted metadata and state transitions.
 - Redact bearer tokens, bot tokens, signing secrets, provider API tokens, and phone numbers.
 - Inject only channel-declared secrets into adapter code.
+- Inject transcription secrets only when the deploy manifest declares transcription and the channel uses `audio.mode: "transcribe"`.
 - Prefer acknowledging Telegram/WhatsApp over retry storms when a channel-level limit is exceeded.
+- Keep audio duration and byte limits bounded before provider calls to avoid uncontrolled transcription spend.
 
 ## Minimal Working Example
 
@@ -54,17 +58,42 @@ telegramChannel({
 });
 ```
 
+With audio transcription:
+
+```ts
+export default defineAgent({
+  // ...
+  transcription: {
+    provider: "groq",
+    model: "whisper-large-v3-turbo",
+    secret: "GROQ_API_KEY",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    telegramChannel({
+      name: "support-telegram",
+      audio: { mode: "transcribe" },
+    }),
+  ],
+});
+```
+
 The config contains secret names only. Hosted responses report:
 
 ```txt
 TELEGRAM_BOT_TOKEN: set
 TELEGRAM_WEBHOOK_SECRET: missing
+GROQ_API_KEY: set
 ```
 
 ## Verification
 
 ```sh
 bun test packages/agentkit/src/runtime/channels/adapters.test.ts
+bun test packages/agentkit/src/runtime/transcription.test.ts
 bun test packages/agentkit/src/runtime/deploy.test.ts
 npm run typecheck
 ```
@@ -79,3 +108,6 @@ Redact it to a stable partial form such as `5511******9999`.
 
 Webhook accepts invalid signatures or origin headers:
 Fix `verifyWebhook` for the adapter before enabling provider setup docs.
+
+Raw audio or transcript provider secret appears in output:
+Stop and add a regression test before changing behavior. Delivery APIs may include transcript text in normalized agent messages after successful transcription, but must never include raw bytes or provider secret values.

package/docs/guides/channels-production-handoff.md

@@ -67,7 +67,7 @@ Telegram channel URL: https://<deploy-host>/channels/support-telegram/telegram/t
 Zapster channel URL: https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook
 Required provider webhook settings: Telegram setWebhook URL/secret token; Zapster webhook URL plus optional ZAPSTER_WEBHOOK_TOKEN query parameter
 Required managed secrets: TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET, ZAPSTER_API_KEY, ZAPSTER_INSTANCE_ID, ZAPSTER_WEBHOOK_ID
-Smoke commands: agentkit channels doctor <name>; agentkit channels test <name> --message "hello"; agentkit channels deliveries list <name> --since 1h
+Smoke commands: agentkit channels doctor <name>; agentkit channels test <name> --message "hello"; agentkit channels test-audio <name> --fixture voice-note for audio channels; agentkit transcribe smoke --provider groq for transcription; agentkit channels deliveries list <name> --since 1h
 Rollback command: curl -X DELETE "$AGENTKIT_CLOUD_API_URL/v1/channels/<channel-id>" -H "Authorization: Bearer $AGENTKIT_CLOUD_API_TOKEN"; then remove provider webhook registration before rolling back the Worker
 Known unverified items: any channel with no real provider inbound, no provider_sent outbound, stale buffers, or AGENTKIT_CHANNEL_SEND_DRY_RUN=1
 ```

package/docs/guides/connect-telegram.md

@@ -27,6 +27,12 @@ TELEGRAM_BOT_TOKEN
 TELEGRAM_WEBHOOK_SECRET
 ```
 
+If Telegram audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually:
+
+```txt
+GROQ_API_KEY
+```
+
 ## Files Created Or Edited
 
 - `agentkit.config.ts`: `telegramChannel({ name: "support-telegram" })`.
@@ -66,6 +72,52 @@ telegramChannel({
 })
 ```
 
+## Auto Transcribe Telegram Audio
+
+Telegram voice notes arrive as OGG/Opus. In V1, use Groq for the most obvious Telegram voice-note path because the AgentKit Groq adapter accepts `audio/ogg`.
+
+```ts
+import { defineAgent, telegramChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "openai", model: "gpt-5.4-mini" },
+  instructions: "./prompts/instructions.md",
+  transcription: {
+    provider: "groq",
+    model: "whisper-large-v3-turbo",
+    secret: "GROQ_API_KEY",
+    language: "pt",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    telegramChannel({
+      name: "support-telegram",
+      audio: {
+        mode: "transcribe",
+      },
+    }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+Processing order:
+
+1. AgentKit validates `X-Telegram-Bot-Api-Secret-Token`.
+2. Telegram `voice` or `audio` payloads become normalized audio messages.
+3. AgentKit records `audio_received` and enqueues a channel job before acknowledging Telegram.
+4. The retryable channel worker calls Telegram `getFile`, downloads the file with `TELEGRAM_BOT_TOKEN`, and does not log the token.
+5. AgentKit sends the audio bytes to the configured transcription provider using the user's managed secret.
+6. The agent run receives a text message with the transcript.
+
+OpenAI transcription can be used for Telegram files that arrive as MP3, MP4, MPEG, MPGA, M4A, WAV, or WEBM. Telegram voice notes are usually OGG/Opus, so they should use Groq in V1 unless the provider payload is converted before it reaches AgentKit.
+
 ## Setup Behavior
 
 `agentkit channels setup support-telegram` is read-only and prints the webhook URL.
@@ -89,6 +141,8 @@ Against AgentKit Cloud, `--apply` runs through the Cloud API and uses managed ho
 ```sh
 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 show <delivery-id>
 ```
 
@@ -108,3 +162,9 @@ The incoming Telegram secret token does not match `TELEGRAM_WEBHOOK_SECRET`.
 
 `channel_payload_invalid`:
 The update is malformed or is not a supported private text message.
+
+`transcription_secret_missing`:
+Set `GROQ_API_KEY` or the custom secret named in `transcription.secret` as a managed hosted secret.
+
+`transcription_audio_format_unsupported`:
+The configured transcription provider does not accept the Telegram file format. Use Groq for OGG/Opus voice notes in V1. `agentkit inspect` warns when a Telegram channel uses `audio.mode: "transcribe"` with OpenAI transcription.

package/docs/guides/connect-whatsapp-zapster.md

@@ -33,6 +33,18 @@ Optional hardening secret:
 ZAPSTER_WEBHOOK_TOKEN
 ```
 
+If WhatsApp audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually:
+
+```txt
+OPENAI_API_KEY
+```
+
+or:
+
+```txt
+GROQ_API_KEY
+```
+
 ## Files Created Or Edited
 
 - `agentkit.config.ts`: `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })`.
@@ -73,6 +85,53 @@ whatsappChannel({
 })
 ```
 
+## Auto Transcribe WhatsApp Audio
+
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on the Zapster channel.
+
+```ts
+import { defineAgent, whatsappChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "openai", model: "gpt-5.4-mini" },
+  instructions: "./prompts/instructions.md",
+  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",
+      },
+    }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+Processing order:
+
+1. AgentKit validates Zapster origin headers and the optional webhook token.
+2. Zapster audio payloads become normalized audio messages.
+3. AgentKit records `audio_received` and enqueues a channel job before acknowledging Zapster.
+4. The retryable channel worker downloads the media URL from a trusted Zapster HTTPS host using `ZAPSTER_API_KEY`.
+5. AgentKit sends the audio bytes to the configured transcription provider using the user's managed secret.
+6. The agent run receives a text message with the transcript.
+
+Zapster payloads must include a media download URL such as `audio.downloadUrl`, `audio.url`, `audio.mediaUrl`, or the snake_case equivalents. The URL must be HTTPS and hosted by Zapster; AgentKit rejects arbitrary webhook-provided hosts before sending `ZAPSTER_API_KEY`. If Zapster sends only a media ID without a download URL, AgentKit records `channel_audio_download_unavailable` and does not create an agent run for that audio in V1.
+
 ## Setup Behavior
 
 `agentkit channels setup support-whatsapp` prints the stable AgentKit webhook URL. Paste it into Zapster webhook settings.
@@ -125,3 +184,9 @@ Zapster is not sending the expected instance/webhook IDs, or the optional query
 
 `channel_unsupported_message_type` or skipped delivery:
 The inbound WhatsApp event was not supported text. Inspect the delivery record for provider metadata.
+
+`channel_audio_download_unavailable`:
+Zapster sent an audio event without a usable media download URL, or the URL was not an HTTPS Zapster media host. Configure Zapster to include a trusted Zapster media URL in webhook payloads, or add a Zapster media lookup adapter before enabling `audio.mode: "transcribe"`.
+
+`transcription_secret_missing`:
+Set `OPENAI_API_KEY`, `GROQ_API_KEY`, or the custom secret named in `transcription.secret` as a managed hosted secret.

package/docs/guides/prepare-deploy.md

@@ -192,7 +192,9 @@ Before a hosted production deploy, run:
 npm run agentkit -- deploy doctor
 ```
 
-The doctor checks AgentKit Cloud login, alpha deploy entitlement, online deploy capacity, declared hosted secrets, local `.env` names that have not been uploaded with `agentkit secret set`, and private-access runtime token handling. `agentkit deploy` runs the same readiness check automatically before building and uploading the artifact.
+The doctor checks AgentKit Cloud login, Node version, alpha deploy entitlement, online deploy capacity, declared hosted secrets, local `.env` names that have not been uploaded with `npm run agentkit -- secret set`, and private-access runtime token handling. `agentkit deploy` runs the same readiness check automatically before building and uploading the artifact.
+
+If the capsule configures `composioManaged({...})`, the doctor also checks the paid `managed_composio` entitlement. `COMPOSIO_API_KEY` is AgentKit-managed in this path; the user must not set it with `agentkit secret set`. Operators configure `AGENTKIT_SECRET_COMPOSIO_API_KEY` and per-toolkit `AGENTKIT_COMPOSIO_AUTH_CONFIG_<TOOLKIT>` values on the control plane.
 
 `alpha_access_required`:
 

package/docs/llms-full.txt

@@ -56,8 +56,13 @@ agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|met
 agentkit channels setup <name> [--apply] [--api <url>]
 agentkit channels status <name> [--api <url>]
 agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
+agentkit channels test-audio <name> [--fixture voice-note|audio-file|<path>] [--api <url>]
 agentkit channels deliveries list <name> [--api <url>]
 agentkit channels deliveries show <delivery-id> [--api <url>]
+agentkit integrations status [--api <url>]
+agentkit integrations connect composio [--toolkit <slug>] [--callback-url <url>] [--api <url>]
+agentkit skills status
+agentkit skills sync
 agentkit inspect
 agentkit build [--target cloudflare|container]
 agentkit login --token <token>
@@ -68,6 +73,7 @@ agentkit deploy smoke [--message <text>] [--api <url>]
 agentkit deploy status
 agentkit deploy pause
 agentkit deploy resume
+agentkit transcribe smoke [--provider test|openai|groq] [--model <model>] [--fixture <audio-file>]
 agentkit secret set <NAME> <VALUE>
 agentkit secret set <NAME> --stdin
 agentkit secret set <NAME> --from-env [ENV_NAME]
@@ -93,6 +99,8 @@ agentkit help commands
 
 Prefer `env set --stdin` or `--from-env` for local secret values, and prefer `secret set --stdin`, `--from-env`, or `--from-local-env` for hosted secrets. Inline `<VALUE>` forms exist for simple non-sensitive values, but agents should avoid putting secrets in shell history.
 
+Managed Composio is configured with `composioManaged({...})` in `agentkit.config.ts` and is paid hosted AgentKit infrastructure. It requires a non-anonymous AgentKit Cloud deploy with `managed_composio`, uses one Composio settings profile per agent, injects `COMPOSIO_API_KEY` as an AgentKit-managed secret, and exposes the generated `agentkit_composio_execute` tool only for explicit configured action slugs. See `docs/guides/add-managed-composio.md`.
+
 Planned commands described by the contract but not implemented yet:
 
 ```sh
@@ -398,11 +406,13 @@ agentkit channels list
 agentkit channels add telegram support-telegram
 agentkit channels setup 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
 agentkit channels deliveries show <delivery-id>
 ```
 
-`channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`.
+`channels connect` creates or refreshes the channel resource, validates secrets, runs provider setup when supported, then runs the official synthetic smoke. `channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`.
 
 Default tests are offline. Real provider smoke tests are opt-in:
 
@@ -796,6 +806,8 @@ Account/access flow:
 agentkit secret set OPENAI_API_KEY --from-local-env
 agentkit secret sync --from-local
 agentkit secret list
+agentkit skills status
+agentkit skills sync
 agentkit access token create website-chat --out .agentkit/website-chat-access-token.json
 agentkit access token list
 ```

package/docs/llms.txt

@@ -16,6 +16,7 @@ Task guides:
 - Build container artifact: `agentkit build --target container`
 - Generate VPS handoff: `agentkit deploy --target vps --host agent.example.com --dry-run`
 - Add hosted channels: `docs/guides/add-channel.md`
+- Add AgentKit-managed Composio: `docs/guides/add-managed-composio.md`
 - Buffer rapid channel messages: `docs/guides/add-channel.md#buffer-bursty-messages`
 - Connect Telegram: `docs/guides/connect-telegram.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
@@ -48,7 +49,13 @@ agentkit channels add telegram support-telegram
 agentkit channels setup 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
+agentkit integrations status
+agentkit integrations connect composio --toolkit gmail
+agentkit skills status
+agentkit skills sync
 agentkit login --token agk_user_...
 agentkit deploy doctor
 agentkit deploy --smoke "hello"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.17",
   "private": false,
   "type": "module",
   "repository": {