@andreprado/agentkit 0.1.0-alpha.16 → 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

@@ -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,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/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

@@ -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/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.16",
+  "version": "0.1.0-alpha.17",
   "private": false,
   "type": "module",
   "repository": {

package/src/cli/commands/channels.ts

@@ -162,8 +162,10 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     let channel = created.channel;
     printChannelStatus(channel);
     printSecretRepairHint(channel);
+    console.log("Channel resource: created_or_updated");
 
     if (hasMissingRequiredSecrets(channel)) {
+      console.log("Secrets: missing");
       console.log("");
       console.log("Connect blocked: set the missing managed secrets, then rerun this same command.");
       console.log("Run: npm run agentkit -- secret sync --from-local");
@@ -171,31 +173,40 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
       return;
     }
 
+    console.log("Secrets: validated");
+
     if (channel.type === "telegram") {
       const setup = await applyTelegramWebhook(channel, args.flags.api);
       channel = setup.channel ?? channel;
+      console.log("Telegram setWebhook: OK");
       console.log("Telegram webhook confirmed.");
       if (setup.setup?.get_webhook_info) {
         console.log(`Telegram pending updates: ${setup.setup.get_webhook_info.pending_update_count}`);
       }
 
-      const smoke = await runChannelSmoke(channel, args.flags.api, args.flags.message);
-      console.log(`Smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
       printTelegramHumanNextStep(channel.name, setup.setup?.bot_username);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
       return;
     }
 
     if (channel.type === "whatsapp" && channel.provider === "zapster") {
-      const smoke = await runChannelSmoke(channel, args.flags.api, args.flags.message);
-      console.log(`Webhook smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
       console.log(`Next human step: paste ${channel.webhook_url} into ${channel.provider}'s webhook settings.`);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
     } else if (channel.type === "whatsapp") {
       console.log("Smoke: skipped until the provider webhook is configured.");
       console.log(`Next human step: paste ${channel.webhook_url} into ${channel.provider}'s webhook settings.`);
     } else {
-      const smoke = await runChannelSmoke(channel, args.flags.api, args.flags.message);
-      console.log(`Smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
       console.log(`Next human step: use ${channel.webhook_url} from your website client.`);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
     }
     return;
   }
@@ -274,6 +285,25 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     return;
   }
 
+  if (subcommand === "test-audio") {
+    if (!first) {
+      throw new Error("Usage: agentkit channels test-audio <name> [--fixture voice-note|audio-file|<path>]");
+    }
+
+    const channel = await resolveCloudChannelByName(first, args.flags.api);
+    const apiUrl = parseCloudApiUrl(args.flags.api);
+    const body = await channelAudioTestBody(channel, args.flags.fixture);
+    const signed = await runServerSignedChannelTest(channel, apiUrl, body);
+    const response = signed.response;
+    const payload = signed.payload;
+
+    console.log(JSON.stringify(payload, null, 2));
+    if (!response.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (subcommand === "deliveries") {
     if (first === "list") {
       if (!second) {
@@ -367,7 +397,7 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
   }
 
   throw new Error(
-    "Usage: agentkit channels list | add | connect | setup | status | doctor | test | deliveries list | deliveries show | buffers list | buffers show | buffers flush | buffers clear | buffers retry",
+    "Usage: agentkit channels list | add | connect | setup | status | doctor | test | test-audio | deliveries list | deliveries show | buffers list | buffers show | buffers flush | buffers clear | buffers retry",
   );
 }
 
@@ -419,6 +449,20 @@ async function runChannelSmoke(
   return { status: "unknown" };
 }
 
+async function runConnectSmoke(
+  run: () => Promise<{ status: string; delivery_id?: string }>,
+): Promise<{ status: string; delivery_id?: string } | null> {
+  try {
+    const smoke = await run();
+    console.log(`Synthetic smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+    return smoke;
+  } catch (error) {
+    console.log("Synthetic smoke: failed");
+    console.log(`  ${formatCommandError(error)}`);
+    return null;
+  }
+}
+
 async function runServerSignedChannelTest(
   channel: CloudChannel,
   apiUrl: string,
@@ -601,6 +645,10 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
+function formatCommandError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 async function readDeployStateIfExists(cwd: string): Promise<DeployState | null> {
   return readLocalDeployStateIfExists(cwd);
 }
@@ -974,6 +1022,70 @@ async function channelTestBody(
   });
 }
 
+async function channelAudioTestBody(
+  channel: CloudChannel,
+  fixtureFlag: string | boolean | undefined,
+): Promise<string> {
+  if (typeof fixtureFlag === "string" && isExplicitFixturePath(fixtureFlag)) {
+    return readFile(resolve(process.cwd(), fixtureFlag), "utf8");
+  }
+
+  const fixture = typeof fixtureFlag === "string" ? fixtureFlag : "voice-note";
+
+  if (channel.type === "telegram") {
+    if (fixture !== "voice-note" && fixture !== "telegram-voice-note" && fixture !== "telegram-audio-message") {
+      throw new Error('Telegram audio smoke supports --fixture voice-note or --fixture telegram-voice-note.');
+    }
+
+    return JSON.stringify({
+      update_id: Date.now(),
+      message: {
+        message_id: 1,
+        date: Math.floor(Date.now() / 1000),
+        chat: { id: 456, type: "private" },
+        from: { id: 123, first_name: "AgentKit" },
+        voice: {
+          file_id: `agentkit_voice_${Date.now()}`,
+          file_unique_id: `agentkit_voice_unique_${Date.now()}`,
+          duration: 12,
+          mime_type: "audio/ogg",
+          file_size: 42,
+        },
+      },
+    });
+  }
+
+  if (channel.type === "whatsapp" && channel.provider === "zapster") {
+    if (fixture !== "voice-note" && fixture !== "audio-file" && fixture !== "zapster-audio" && fixture !== "zapster-audio-message") {
+      throw new Error('Zapster audio smoke supports --fixture voice-note, --fixture audio-file, or --fixture zapster-audio.');
+    }
+
+    return JSON.stringify({
+      event_id: `zap_evt_audio_${Date.now()}`,
+      instance_id: "local",
+      message: {
+        id: `wamid.audio.${Date.now()}`,
+        from: "5511999999999",
+        type: "audio",
+        audio: {
+          id: `media_audio_${Date.now()}`,
+          url: `https://api.zapsterapi.com/media/audio/media_audio_${Date.now()}.ogg`,
+          mime_type: "audio/ogg",
+          duration: 12,
+          file_size: 42,
+          ...(fixture === "voice-note" ? { ptt: "true" } : {}),
+        },
+      },
+    });
+  }
+
+  throw new Error(`Audio smoke is not supported for ${channel.type}/${channel.provider}.`);
+}
+
+function isExplicitFixturePath(value: string): boolean {
+  return value.includes("/") || value.startsWith(".") || value.endsWith(".json");
+}
+
 function channelTestHeaders(channel: CloudChannel): Headers {
   const headers = new Headers({ "Content-Type": "application/json" });