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

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

@@ -24,13 +24,13 @@ agentkit channels deliveries list support-telegram
 agentkit channels buffers list support-telegram
 ```
 
-Use `--api <url>` with hosted commands when testing against a non-default AgentKit Cloud API.
+Use `--api <url>` only when the owner gives you a non-default AgentKit Cloud API URL.
 
 ## Files Created Or Edited
 
 - `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, or `whatsappChannel`.
 - `.agentkit/deploy.json`: written by `agentkit deploy`; used by `agentkit channels ...`.
-- No user Turso tables: AgentKit channel resources, dedupe, identities, queue state, and delivery logs are control-plane owned.
+- No user Turso tables: AgentKit owns channel resources, dedupe, identities, queue state, and delivery logs.
 - Website channel clients must send `AGENTKIT_WEBSITE_CHANNEL_TOKEN` as `Authorization: Bearer <token>` or `X-AgentKit-Channel-Token`.
 
 ## Minimal Working Example
@@ -160,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
 ```

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

@@ -0,0 +1,161 @@
+# 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_EVENTS_LIST",
+          "GOOGLECALENDAR_CREATE_EVENT",
+          "GOOGLECALENDAR_UPDATE_EVENT",
+        ],
+      },
+      confirmExternalWrites: true,
+    }),
+  ],
+  access: {
+    mode: "private",
+  },
+  storage: {
+    driver: "agentkit",
+    database: {
+      driver: "turso",
+    },
+  },
+});
+```
+
+## Deploy
+
+```sh
+agentkit login --token agk_user_...
+agentkit deploy doctor
+agentkit deploy
+agentkit integrations status --toolkit googlecalendar
+```
+
+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.
+
+## Calendar Defaults
+
+For Google Calendar agents, include read and write actions together. Do not expose only `GOOGLECALENDAR_CREATE_EVENT`; users naturally ask to see availability before booking.
+
+Use these starter actions:
+
+```ts
+googlecalendar: [
+  "GOOGLECALENDAR_EVENTS_LIST",
+  "GOOGLECALENDAR_CREATE_EVENT",
+  "GOOGLECALENDAR_UPDATE_EVENT",
+]
+```
+
+`GOOGLECALENDAR_CREATE_EVENT` requires extra care:
+
+- `start_datetime` must be explicit UTC RFC3339, such as `2026-06-03T15:00:00Z` for 12:00 in `America/Sao_Paulo`.
+- `event_duration_minutes` or `event_duration_hour` must be explicit. AgentKit blocks the implicit Composio default because `event_duration_minutes` defaults to 30.
+- Confirm the final title, date, local time, duration, timezone, and attendees/location when relevant before creating or updating an event.
+
+## Write Confirmation
+
+Managed Composio requires confirmation for external write actions by default. For actions such as create, update, delete, send, patch, move, insert, clear, remove, import, or quick add, the generated `agentkit_composio_execute` tool requires `confirmed: true`.
+
+Set `confirmed: true` only after the user confirms the exact external change. If a capsule intentionally handles confirmation elsewhere, disable this guard explicitly:
+
+```ts
+composioManaged({
+  toolkits: ["googlecalendar"],
+  tools: {
+    googlecalendar: ["GOOGLECALENDAR_EVENTS_LIST", "GOOGLECALENDAR_CREATE_EVENT"],
+  },
+  confirmExternalWrites: false,
+})
+```
+
+## Verification
+
+```sh
+agentkit inspect
+agentkit build --target cloudflare
+agentkit deploy doctor
+agentkit integrations status --toolkit googlecalendar
+```
+
+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`.
+- `deploy doctor` reports each configured toolkit auth config as present before the connect link flow.
+
+## Troubleshooting
+
+`managed_composio_entitlement_required`:
+
+Log in with a paid AgentKit Cloud account that has `managed_composio`.
+
+`managed_composio_auth_config_missing`:
+
+The AgentKit Cloud account is entitled, but the requested toolkit is not available for managed Composio yet. Report the exact error code and toolkit slug to the AgentKit owner.
+
+`managed_composio_not_configured`:
+
+Managed Composio is not available for this AgentKit Cloud environment. Use BYO `defineTool` wrappers for now or ask the owner to enable managed Composio for the account.
+
+`integration_toolkit_required`:
+
+The deploy has multiple configured toolkits. Re-run connect with `--toolkit <slug>`.

package/docs/guides/channel-security.md

@@ -2,52 +2,39 @@
 
 ## Goal
 
-Keep channel webhooks, delivery logs, provider sends, and managed secrets safe by default.
+Configure website, Telegram, and WhatsApp channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
 
 ## When To Use It
 
-Use this before adding a channel provider, changing webhook validation, adding delivery logging, or enabling real-provider smoke tests.
+Use this when a coding agent adds or changes channels in an Agent Capsule, enables audio transcription, inspects deliveries, or prepares a hosted deploy that receives provider webhooks.
 
 ## Commands
 
 ```sh
 agentkit inspect
 agentkit channels status <name>
+agentkit channels doctor <name>
+agentkit channels deliveries list <name> --since 24h
 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
 ```
 
-Real-provider gates are opt-in:
-
-```sh
-AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
-AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
-```
-
-Telegram smoke also requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
-
-Zapster smoke also requires `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `AGENTKIT_ZAPSTER_TO`. `AGENTKIT_ZAPSTER_SEND_URL` is optional and defaults to `https://api.zapsterapi.com/v1/wa/messages`.
-
 ## Files Created Or Edited
 
-- `agentkit.config.ts`: secret names only.
-- Managed hosted secrets: production secret values, no readback.
-- Delivery records: hashes, statuses, provider event IDs, redacted metadata.
+- `agentkit.config.ts`: channel names, provider choices, audio/buffer config, and secret names only.
+- `.env.schema`: local secret names only when the capsule needs a local provider or local smoke.
+- `.env`: local-only secret values; do not commit it.
+- Hosted managed secrets: production secret values with no readback.
 
 ## Safety Rules
 
 - Public webhook URLs are not permission grants.
-- 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.
+- Keep provider tokens, webhook secrets, bot tokens, transcription keys, and bearer tokens out of source files.
+- Put secret names in `agentkit.config.ts`; put local values in ignored `.env`; upload production values with `agentkit secret set` or `agentkit secret sync`.
+- Do not store raw webhook bodies, raw audio, or provider secret values in tools, prompts, evals, fixtures, or delivery notes.
+- Inspect delivery IDs, hashes, redacted metadata, and statuses instead of raw provider payloads.
+- Keep channel plumbing out of the agent's application database. The user's Turso tables are for the agent's business data.
+- Enable audio transcription only when the capsule declares a transcription provider and bounded `limits`.
+- Keep channel buffer limits bounded so bursty client messages cannot create unbounded runs or provider spend.
 
 ## Minimal Working Example
 
@@ -81,7 +68,7 @@ export default defineAgent({
 });
 ```
 
-The config contains secret names only. Hosted responses report:
+The config contains secret names only. Hosted responses report status, not values:
 
 ```txt
 TELEGRAM_BOT_TOKEN: set
@@ -92,22 +79,32 @@ 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
+npm run agentkit -- inspect
+npm run agentkit -- deploy doctor
+npm run agentkit -- channels status <name>
+npm run agentkit -- channels doctor <name>
+```
+
+For a synthetic channel smoke after deploy:
+
+```sh
+npm run agentkit -- channels test <name> --message "hello"
+npm run agentkit -- channels deliveries list <name> --since 1h
 ```
 
 ## Troubleshooting
 
 Secret value appears in output:
-Stop and add a regression test before changing behavior. Delivery APIs must never return secret values.
+Stop and remove the value from source, fixtures, prompts, evals, and delivery notes. Hosted delivery APIs must not return secret values.
 
 Phone number appears in delivery logs:
-Redact it to a stable partial form such as `5511******9999`.
+Use the redacted delivery metadata and avoid pasting full phone numbers into committed fixtures.
+
+`channel_secret_missing`:
+Set the named hosted secret with `agentkit secret set <NAME> --from-local-env` or `agentkit secret sync --from-local`.
 
-Webhook accepts invalid signatures or origin headers:
-Fix `verifyWebhook` for the adapter before enabling provider setup docs.
+`channel_signature_invalid`:
+Check that the provider webhook secret/token configured in the provider dashboard matches the hosted secret name declared by the channel.
 
-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.
+Raw audio appears in files or logs:
+Remove it. AgentKit may pass transcript text into the normalized agent message after successful transcription, but raw audio belongs outside committed capsule files.

package/docs/guides/connect-telegram.md

@@ -141,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>
 ```
 
@@ -165,4 +167,4 @@ The update is malformed or is not a supported private text message.
 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.
+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/debug-channel.md

@@ -0,0 +1,141 @@
+# Debug A Channel
+
+## Goal
+
+Diagnose website, Telegram, or WhatsApp channel setup, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
+
+## When To Use It
+
+Use this when a hosted channel is not responding, a provider is retrying messages, audio transcription is failing, or delivery status does not match the user's expectation.
+
+## Commands
+
+```sh
+agentkit channels list
+agentkit channels status <name>
+agentkit channels doctor <name>
+agentkit channels test <name> --message "hello"
+agentkit channels test-audio <name> --fixture voice-note
+agentkit transcribe smoke --provider groq
+agentkit channels test <name> --fixture ./fixtures/provider-event.json
+agentkit channels deliveries list <name> --since 24h
+agentkit channels deliveries show <delivery-id>
+agentkit channels buffers list <name>
+agentkit channels buffers show <conversation-id>
+agentkit channels buffers flush <conversation-id>
+agentkit channels buffers clear <conversation-id>
+agentkit channels buffers retry <conversation-id>
+```
+
+## Files Created Or Edited
+
+Debugging should not require source edits. Use fixtures only when reproducing provider payload shape, and never commit provider secrets, full phone numbers, raw audio, or private client data.
+
+## Delivery States
+
+```txt
+received
+validated
+duplicate
+audio_received
+audio_downloaded
+transcribing
+transcribed
+buffered
+queued
+running
+agent_completed
+provider_request_built
+provider_sent
+adapter_stubbed
+delivered
+provider_failed
+failed
+dead_lettered
+skipped
+```
+
+## Minimal Working Example
+
+```sh
+agentkit channels test support-telegram --message "hello"
+agentkit channels deliveries list support-telegram --since 1h
+agentkit channels deliveries show del_123
+```
+
+Expected `show` output includes signature status, dedupe key, queue/run state, outbound provider request ID when available, and a normalized error envelope.
+
+## Safety Rules
+
+- Inspect delivery IDs, hashes, statuses, and redacted metadata rather than raw provider payloads.
+- Never paste provider secrets into fixtures or prompts.
+- Treat `adapter_stubbed` as a dry-run send, not proof that a client received a message.
+- Before replaying or flushing buffered conversations, confirm the channel name and conversation ID.
+- Keep local `.env` values ignored and upload hosted production values through AgentKit secret commands.
+
+## Troubleshooting By Error Code
+
+`channel_not_found`:
+The webhook URL points to an unknown or deleted channel. Stable hosted URLs use the channel name, for example `/channels/support-whatsapp/whatsapp/zapster/webhook`; old `chn_*` URLs are accepted only for compatibility.
+
+`agentkit channels test <name>` is the official synthetic smoke. If it fails while `channels list`, `status`, or `doctor` find the channel, rerun against the current deploy state in `.agentkit/deploy.json`.
+
+`channel_disabled`:
+The channel was disabled. Re-add or recreate it.
+
+`channel_secret_missing`:
+The hosted secret metadata says a required channel secret is missing. Set it with `agentkit secret set <NAME> --from-local-env` or `agentkit secret sync --from-local`.
+
+`channel_signature_invalid`:
+Provider authenticity validation failed. Check the provider webhook secret, token, or origin settings.
+
+`channel_payload_invalid`:
+The provider payload is malformed or does not match the route provider.
+
+`audio_received`:
+The webhook contained a supported audio message and the channel is entering the audio handling path.
+
+`audio_downloaded`:
+The retryable channel worker downloaded the provider media file into memory. The delivery metadata should include only redacted size, MIME, and provider IDs.
+
+`transcribing`:
+AgentKit is calling the configured transcription provider with the user's managed transcription secret.
+
+`transcribed`:
+Transcription succeeded and the queued agent message contains transcript text instead of raw audio.
+
+`channel_event_duplicate` or `duplicate`:
+The provider retried an already-processed event. No second agent run should be created.
+
+`buffered`:
+The message is accepted and waiting inside a per-conversation channel buffer. It should move to `queued` after the quiet window, max wait, max message count, or max character count.
+
+`adapter_stubbed`:
+The adapter built the outbound request in explicit dry-run mode. The provider was not called.
+
+`provider_sent`:
+The provider API accepted the outbound request and returned a provider message ID.
+
+`channel_limit_exceeded`:
+Backpressure skipped the message before queueing.
+
+`channel_audio_download_unavailable`:
+The channel provider reported audio but did not include enough metadata for AgentKit to download it.
+
+`transcription_secret_missing`:
+The transcription provider secret declared in `agentkit inspect` is not set as a managed hosted secret.
+
+`transcription_audio_too_large` or `transcription_audio_too_long`:
+The audio exceeded `transcription.limits` or the channel-level `audio.limits`.
+
+`transcription_audio_format_unsupported`:
+The configured transcription provider does not accept this audio MIME type or file extension.
+
+`transcription_provider_unavailable`:
+The transcription provider returned a retryable error, usually HTTP 429 or a server-side failure.
+
+`channel_provider_unavailable`:
+The agent run or provider send path failed with a retryable provider condition.
+
+`channel_delivery_dead_lettered`:
+The queue exhausted retries. Inspect the delivery and replay manually only after fixing the cause.

package/docs/guides/prepare-deploy.md

@@ -25,7 +25,7 @@ npm run agentkit -- db migrate
 npm run chat -- --message "hello"
 ```
 
-All scaffold, local dev, chat, eval, inspect, database, and build commands are token-free. Only hosted production deploy and hosted control-plane mutations require an invited AgentKit Cloud token:
+All scaffold, local dev, chat, eval, inspect, database, and build commands are token-free. Hosted production deploy and hosted AgentKit Cloud changes require an invited AgentKit Cloud token:
 
 ```sh
 npm run agentkit -- login --token agk_user_...
@@ -134,7 +134,7 @@ npm run agentkit -- chat-ui --deploy
 npm run agentkit -- access token list
 ```
 
-For private hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json`. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
+For private hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json`. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. The hosted Chat UI shows the conversation id, tool calls, tool errors, and a new-conversation control; use `npm run agentkit -- conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
 
 When the UI is running, open the printed `Chat:` URL and tell the owner the exact URL. If the capsule is still on `test/fake`, say the UI was tested only with the deterministic fake provider.
 
@@ -147,6 +147,7 @@ All required secret names are declared
 Prompt path exists
 Tools have input schemas
 Dangerous tools have permissions
+Managed Composio toolkit auth configs are present when configured
 Provider model is supported by AgentKit
 schema.sql is idempotent
 README/AGENTS/CLAUDE match the capsule
@@ -172,7 +173,7 @@ echo 'OPENAI_API_KEY=sk-...' >> .env
 
 Missing hosted secret:
 
-Set the secret in AgentKit Cloud or the configured control plane:
+Set the secret in AgentKit Cloud:
 
 ```sh
 npm run agentkit -- secret set OPENAI_API_KEY --from-local-env
@@ -192,7 +193,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`.
 
 `alpha_access_required`:
 
@@ -201,9 +204,3 @@ Log in with an invited alpha account:
 ```sh
 npm run agentkit -- login --token agk_user_...
 ```
-
-## Operator Notes
-
-This section is for AgentKit maintainers, not for capsule-building agents.
-
-`agentkit deploy` sends the capsule artifact to the configured AgentKit Cloud API. The control plane owns infrastructure selection, provisioning, managed secrets, and public URL creation. Use `AGENTKIT_CLOUD_API_URL` only when testing a non-default control plane.

package/docs/llms-full.txt

@@ -51,13 +51,19 @@ agentkit db seed [--file <path>]
 agentkit eval run
 agentkit conversations list
 agentkit conversations show <conversation-id>
+agentkit conversations trace <conversation-id> [--deploy]
 agentkit channels list
 agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
 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 [--toolkit <slug>] [--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 +74,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 +100,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, validates toolkit auth configs during `agentkit deploy doctor`, and exposes the generated `agentkit_composio_execute` tool only for explicit configured action slugs. Calendar starters should include `GOOGLECALENDAR_EVENTS_LIST`, `GOOGLECALENDAR_CREATE_EVENT`, and `GOOGLECALENDAR_UPDATE_EVENT`; create-event calls must pass UTC `start_datetime` plus explicit duration. Managed external write actions require tool input `confirmed: true` by default unless the integration sets `confirmExternalWrites: false`. See `docs/guides/add-managed-composio.md`.
+
 Planned commands described by the contract but not implemented yet:
 
 ```sh
@@ -372,7 +381,6 @@ Useful guides:
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Debug a channel: `docs/guides/debug-channel.md`
 - Channel security: `docs/guides/channel-security.md`
-- Production handoff: `docs/guides/channels-production-handoff.md`
 
 Telegram required secrets:
 
@@ -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:
 
@@ -675,6 +685,7 @@ GET  /_agentkit
 POST /v1/chat
 GET  /v1/conversations
 GET  /v1/conversations/:id
+GET  /v1/conversations/:id/trace
 ```
 
 Chat request:
@@ -694,6 +705,7 @@ After chat:
 ```sh
 agentkit conversations list
 agentkit conversations show <conversation-id>
+agentkit conversations trace <conversation-id>
 ```
 
 List output columns:
@@ -702,7 +714,7 @@ List output columns:
 id	title	updated_at	messages
 ```
 
-Show output includes the conversation id, title, updated timestamp, and each message as `role: content`.
+Show output includes the conversation id, title, updated timestamp, and each message as `role: content`. Trace output includes stored messages and tool calls for the conversation.
 
 ## Evals
 
@@ -786,9 +798,9 @@ agentkit deploy smoke --message "hello"
 agentkit chat-ui --deploy
 ```
 
-`agentkit deploy doctor` checks AgentKit Cloud login, `cloudflare_deploy_alpha`, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, and writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json` for private hosted deploys. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code. Production alpha deploys require an account with `cloudflare_deploy_alpha`; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
+`agentkit deploy doctor` checks AgentKit Cloud login, `cloudflare_deploy_alpha`, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, managed Composio API/auth-config readiness by toolkit, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, updates the current project deploy slot by default, and writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json` for private hosted deploys. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code, shows the conversation id and tool calls, and supports starting a new conversation. Use `agentkit conversations trace <conversation-id> --deploy` to pull hosted conversation messages and tool calls from the last deploy. Production alpha deploys require an account with `cloudflare_deploy_alpha`; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
 
-The CLI defaults to the hosted AgentKit Cloud API at `https://agentkit-cloud.aibuilders.com.br`. Use `AGENTKIT_CLOUD_API_URL` or `agentkit deploy --api <url>` only for local or alternate control-plane tests.
+The CLI defaults to the hosted AgentKit Cloud API at `https://agentkit-cloud.aibuilders.com.br`. Use `AGENTKIT_CLOUD_API_URL` or `agentkit deploy --api <url>` only when the owner gives you a non-default AgentKit Cloud API URL.
 
 Account/access flow:
 
@@ -796,6 +808,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
 ```