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

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

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

@@ -39,8 +39,13 @@ export default defineAgent({
       toolkits: ["gmail", "googlecalendar"],
       tools: {
         gmail: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
-        googlecalendar: ["GOOGLECALENDAR_CREATE_EVENT"],
+        googlecalendar: [
+          "GOOGLECALENDAR_EVENTS_LIST",
+          "GOOGLECALENDAR_CREATE_EVENT",
+          "GOOGLECALENDAR_UPDATE_EVENT",
+        ],
       },
+      confirmExternalWrites: true,
     }),
   ],
   access: {
@@ -61,7 +66,7 @@ export default defineAgent({
 agentkit login --token agk_user_...
 agentkit deploy doctor
 agentkit deploy
-agentkit integrations status
+agentkit integrations status --toolkit googlecalendar
 ```
 
 Expected readiness:
@@ -83,23 +88,41 @@ 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
+## Calendar Defaults
 
-Trusted AgentKit Cloud operators grant access and configure Composio auth configs:
+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.
 
-```sh
-npm run agentkit:operator -- accounts grant user@example.com --managed-composio
+Use these starter actions:
+
+```ts
+googlecalendar: [
+  "GOOGLECALENDAR_EVENTS_LIST",
+  "GOOGLECALENDAR_CREATE_EVENT",
+  "GOOGLECALENDAR_UPDATE_EVENT",
+]
 ```
 
-Required control-plane environment:
+`GOOGLECALENDAR_CREATE_EVENT` requires extra care:
 
-```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>
-```
+- `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
 
-Use one `AGENTKIT_COMPOSIO_AUTH_CONFIG_<TOOLKIT>` value per toolkit slug, uppercased with non-alphanumeric characters converted to `_`.
+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
 
@@ -107,7 +130,7 @@ Use one `AGENTKIT_COMPOSIO_AUTH_CONFIG_<TOOLKIT>` value per toolkit slug, upperc
 agentkit inspect
 agentkit build --target cloudflare
 agentkit deploy doctor
-agentkit integrations status
+agentkit integrations status --toolkit googlecalendar
 ```
 
 Expected:
@@ -117,6 +140,7 @@ Expected:
 - 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
 
@@ -126,11 +150,11 @@ 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.
+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`:
 
-An operator must set `AGENTKIT_SECRET_COMPOSIO_API_KEY` on the control plane.
+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`:
 

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/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
@@ -194,7 +195,7 @@ npm run agentkit -- deploy doctor
 
 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.
+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`:
 
@@ -203,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,6 +51,7 @@ 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>]
@@ -59,7 +60,7 @@ 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 status [--toolkit <slug>] [--api <url>]
 agentkit integrations connect composio [--toolkit <slug>] [--callback-url <url>] [--api <url>]
 agentkit skills status
 agentkit skills sync
@@ -99,7 +100,7 @@ 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`.
+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:
 
@@ -380,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:
 
@@ -685,6 +685,7 @@ GET  /_agentkit
 POST /v1/chat
 GET  /v1/conversations
 GET  /v1/conversations/:id
+GET  /v1/conversations/:id/trace
 ```
 
 Chat request:
@@ -704,6 +705,7 @@ After chat:
 ```sh
 agentkit conversations list
 agentkit conversations show <conversation-id>
+agentkit conversations trace <conversation-id>
 ```
 
 List output columns:
@@ -712,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
 
@@ -796,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:
 

package/docs/llms.txt

@@ -21,9 +21,7 @@ Task guides:
 - Connect Telegram: `docs/guides/connect-telegram.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Follow channel webhook and delivery-log safety rules: `docs/guides/channel-security.md`
-- Prepare Channels for production: `docs/guides/channels-production-handoff.md`
 - Follow secret, access, and tool safety rules: `docs/guides/security-rules.md`
-- Plan repo-local skills for coding agents: `docs/guides/agentkit-skills-architecture.md`
 
 Current local commands:
 
@@ -44,6 +42,7 @@ agentkit knowledge search <query> [--top-k <number>]
 agentkit eval run
 agentkit conversations list
 agentkit conversations show <conversation-id>
+agentkit conversations trace <conversation-id> [--deploy]
 agentkit channels list
 agentkit channels add telegram support-telegram
 agentkit channels setup support-telegram
@@ -52,7 +51,7 @@ 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 status [--toolkit googlecalendar]
 agentkit integrations connect composio --toolkit gmail
 agentkit skills status
 agentkit skills sync
@@ -76,6 +75,8 @@ Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/
 
 UI testing is part of the handoff. For local UI testing, run `agentkit dev`, open the printed `Chat:` URL, and tell the owner the exact URL. After hosted deploy, run `agentkit chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the deploy.
 
+Hosted Chat UI shows the current conversation id, tool calls, tool errors, and a new-conversation control. Use `agentkit conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy.
+
 `test/fake` is deterministic and validates scaffold, direct tool calls, and fake-provider evals. It does not validate natural conversation quality. Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
 
 AgentKit injects the current ISO timestamp, local date, weekday, local date/time, and timezone dynamically into every chat run. Set `timeZone` in `agentkit.config.ts` for scheduling agents so "today", "tomorrow", and weekdays resolve in the business/user timezone; otherwise AgentKit falls back to `AGENTKIT_TIME_ZONE`, valid `TZ`, then the runtime default. Do not hardcode today's date in prompts.
@@ -87,6 +88,7 @@ GET  /_agentkit
 POST /v1/chat
 GET  /v1/conversations
 GET  /v1/conversations/:id
+GET  /v1/conversations/:id/trace
 ```
 
 Local `.env` is for development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted alpha deploys require `cloudflare_deploy_alpha` through `agentkit login --token ...`; production uses managed secrets in the hosted contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.18",
   "private": false,
   "type": "module",
   "repository": {
@@ -18,8 +18,6 @@
     "!src/**/*.test.ts",
     "!src/runtime/fixtures",
     "docs",
-    "!docs/guides/backend-contracts.md",
-    "!docs/guides/debug-channel.md",
     "README.md"
   ],
   "publishConfig": {

package/src/cli/cloud-client.ts

@@ -39,6 +39,18 @@ export type CloudLimitsResponse = {
   };
 };
 
+export type CloudManagedComposioResponse = {
+  managed_composio?: {
+    entitlement?: "active" | "missing" | string;
+    api_key?: "set" | "missing" | string;
+    toolkits?: Array<{
+      toolkit?: string;
+      auth_config_env?: string;
+      auth_config?: "set" | "missing" | string;
+    }>;
+  };
+};
+
 export type CloudProjectResolveResponse = {
   project?: {
     id?: string;