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

package/src/runtime/integrations/composio.ts

@@ -0,0 +1,257 @@
+import type { AgentConfig, AgentTool, ComposioManagedIntegration } from "../../index";
+import { AgentKitError } from "../errors";
+
+export const MANAGED_COMPOSIO_TOOL_NAME = "agentkit_composio_execute";
+export const MANAGED_COMPOSIO_API_KEY_SECRET = "COMPOSIO_API_KEY";
+export const MANAGED_COMPOSIO_WEBHOOK_SECRET = "COMPOSIO_WEBHOOK_SECRET";
+export const MANAGED_COMPOSIO_ENTITLEMENT = "managed_composio";
+export const MANAGED_COMPOSIO_USER_ID_BINDING = "AGENTKIT_MANAGED_COMPOSIO_USER_ID";
+
+export type ResolvedComposioManagedIntegration = ComposioManagedIntegration & {
+  userId: string;
+  allowedTools: string[];
+};
+
+export type ManagedComposioResolutionOptions = {
+  userId?: string;
+  userIdScope?: string;
+};
+
+type ManagedComposioToolInput = {
+  toolSlug: string;
+  arguments: Record<string, unknown>;
+};
+
+type ManagedComposioToolOutput = {
+  successful: boolean;
+  data: unknown;
+  error: unknown;
+  logId: string | null;
+  toolkit: string;
+  toolSlug: string;
+  userId: string;
+};
+
+export function resolveManagedComposioIntegrations(
+  config: Pick<AgentConfig, "name" | "integrations">,
+  options: ManagedComposioResolutionOptions = {},
+): ResolvedComposioManagedIntegration[] {
+  return (config.integrations ?? [])
+    .filter((integration): integration is ComposioManagedIntegration => integration.provider === "composio" && integration.mode === "managed")
+    .map((integration) => ({
+      ...integration,
+      userId: options.userId ?? managedComposioUserId(config.name, options.userIdScope),
+      allowedTools: allowedComposioTools(integration),
+    }));
+}
+
+export function hasManagedComposioIntegration(config: Pick<AgentConfig, "name" | "integrations">): boolean {
+  return resolveManagedComposioIntegrations(config).length > 0;
+}
+
+export function managedComposioRequiredSecrets(config: Pick<AgentConfig, "name" | "integrations">): string[] {
+  return hasManagedComposioIntegration(config) ? [MANAGED_COMPOSIO_API_KEY_SECRET] : [];
+}
+
+export function createManagedComposioTools(
+  config: Pick<AgentConfig, "name" | "integrations">,
+  options: ManagedComposioResolutionOptions = {},
+): AgentTool[] {
+  const integrations = resolveManagedComposioIntegrations(config, options);
+
+  return integrations.flatMap((integration) => {
+    if (integration.allowedTools.length === 0) {
+      return [];
+    }
+
+    const toolkitByTool = new Map<string, string>();
+
+    for (const [toolkit, tools] of Object.entries(integration.tools ?? {})) {
+      for (const tool of tools) {
+        toolkitByTool.set(tool, toolkit);
+      }
+    }
+
+    const tool: AgentTool<ManagedComposioToolInput, ManagedComposioToolOutput> = {
+      name: MANAGED_COMPOSIO_TOOL_NAME,
+      description:
+        "Executes one explicitly allowed AgentKit-managed Composio action for this deployed agent. Use only for configured connected apps.",
+      visibility: "user",
+      secrets: [MANAGED_COMPOSIO_API_KEY_SECRET],
+      permissions: integration.allowedTools.map((toolName) => `composio:${toolName.toLowerCase()}`),
+      timeoutMs: 60_000,
+      inputSchema: {
+        type: "object",
+        properties: {
+          toolSlug: {
+            type: "string",
+            enum: integration.allowedTools,
+            description: "Allowed Composio action slug to execute.",
+          },
+          arguments: {
+            type: "object",
+            additionalProperties: true,
+            description: "Structured arguments for the selected Composio action.",
+          },
+        },
+        required: ["toolSlug", "arguments"],
+        additionalProperties: false,
+      },
+      outputSchema: {
+        type: "object",
+        properties: {
+          successful: { type: "boolean" },
+          data: { type: ["object", "array", "string", "number", "boolean", "null"] },
+          error: { type: ["object", "string", "null"] },
+          logId: { type: ["string", "null"] },
+          toolkit: { type: "string" },
+          toolSlug: { type: "string" },
+          userId: { type: "string" },
+        },
+        required: ["successful", "toolkit", "toolSlug", "userId"],
+        additionalProperties: true,
+      },
+      async execute(input, ctx) {
+        const toolkit = toolkitByTool.get(input.toolSlug);
+
+        if (!toolkit || !integration.allowedTools.includes(input.toolSlug)) {
+          throw new AgentKitError(
+            "composio_tool_not_allowed",
+            `Composio action "${input.toolSlug}" is not allowed by this agent's managed Composio settings.`,
+          );
+        }
+
+        const result = await executeComposioTool({
+          apiKey: ctx.secrets[MANAGED_COMPOSIO_API_KEY_SECRET],
+          userId: integration.userId,
+          toolSlug: input.toolSlug,
+          arguments: input.arguments,
+          signal: ctx.signal,
+        });
+
+        return {
+          successful: result.successful,
+          data: result.data ?? null,
+          error: result.error ?? null,
+          logId: result.log_id ?? null,
+          toolkit,
+          toolSlug: input.toolSlug,
+          userId: integration.userId,
+        };
+      },
+      render(output) {
+        if (output.successful) {
+          return `Composio action ${output.toolSlug} completed.`;
+        }
+
+        return {
+          text: `Composio action ${output.toolSlug} did not complete successfully.`,
+          blocks: [
+            {
+              type: "card",
+              title: "Composio connection or action issue",
+              subtitle: typeof output.error === "string" ? output.error : undefined,
+              fields: [
+                { label: "Toolkit", value: output.toolkit },
+                { label: "Action", value: output.toolSlug },
+              ],
+            },
+          ],
+        };
+      },
+    };
+
+    return [tool];
+  });
+}
+
+export function managedComposioUserId(agentName: string, scope = "local"): string {
+  return `ak_agent_${stableHash(`${scope}:${agentName}`).slice(0, 24)}`;
+}
+
+function allowedComposioTools(integration: ComposioManagedIntegration): string[] {
+  return Array.from(new Set(Object.values(integration.tools ?? {}).flat())).sort();
+}
+
+async function executeComposioTool(input: {
+  apiKey: string | undefined;
+  userId: string;
+  toolSlug: string;
+  arguments: Record<string, unknown>;
+  signal: AbortSignal;
+}): Promise<{ successful: boolean; data?: unknown; error?: unknown; log_id?: string }> {
+  if (!input.apiKey) {
+    throw new AgentKitError("composio_secret_missing", "AgentKit-managed Composio requires COMPOSIO_API_KEY at runtime.");
+  }
+
+  const response = await fetch(
+    `https://backend.composio.dev/api/v3.1/tools/execute/${encodeURIComponent(input.toolSlug)}`,
+    {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-api-key": input.apiKey,
+      },
+      body: JSON.stringify({
+        user_id: input.userId,
+        arguments: input.arguments,
+      }),
+      signal: input.signal,
+    },
+  );
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    throw new AgentKitError(
+      "composio_execution_failed",
+      `Composio action ${input.toolSlug} failed with HTTP ${response.status}: ${readComposioError(payload)}`,
+    );
+  }
+
+  if (!isRecord(payload)) {
+    return { successful: true, data: payload };
+  }
+
+  return {
+    successful: payload.successful !== false,
+    data: payload.data,
+    error: payload.error,
+    log_id: typeof payload.log_id === "string" ? payload.log_id : undefined,
+  };
+}
+
+function readComposioError(payload: unknown): string {
+  if (isRecord(payload)) {
+    if (typeof payload.error === "string") {
+      return payload.error;
+    }
+
+    if (isRecord(payload.error) && typeof payload.error.message === "string") {
+      return payload.error.message;
+    }
+  }
+
+  return "unknown error";
+}
+
+function stableHash(value: string): string {
+  let first = 2166136261;
+  let second = 0x811c9dc5;
+  let third = 0x01000193;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    first ^= code;
+    first = Math.imul(first, 16777619);
+    second ^= code + index;
+    second = Math.imul(second, 1597334677);
+    third ^= code * (index + 1);
+    third = Math.imul(third, 2246822519);
+  }
+
+  return [first, second, third].map((hash) => (hash >>> 0).toString(16).padStart(8, "0")).join("");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/runtime/skills.ts

@@ -0,0 +1,95 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type DefaultSkillFile = {
+  path: string;
+  contents: string;
+};
+
+export type DefaultSkillStatus = {
+  status: "current" | "missing" | "outdated";
+  checked: number;
+  missing: string[];
+  outdated: string[];
+};
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+
+export async function syncDefaultSkillFiles(projectPath: string): Promise<{ files: string[] }> {
+  const files = await loadDefaultSkillFiles();
+
+  for (const file of files) {
+    const absolutePath = join(projectPath, file.path);
+
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, file.contents);
+  }
+
+  return { files: files.map((file) => file.path) };
+}
+
+export async function checkDefaultSkillStatus(projectPath: string): Promise<DefaultSkillStatus> {
+  const files = await loadDefaultSkillFiles();
+  const missing: string[] = [];
+  const outdated: string[] = [];
+
+  for (const file of files) {
+    const absolutePath = join(projectPath, file.path);
+
+    if (!(await pathExists(absolutePath))) {
+      missing.push(file.path);
+      continue;
+    }
+
+    const current = await readFile(absolutePath, "utf8");
+    if (current !== file.contents) {
+      outdated.push(file.path);
+    }
+  }
+
+  return {
+    status: missing.length > 0 ? "missing" : outdated.length > 0 ? "outdated" : "current",
+    checked: files.length,
+    missing,
+    outdated,
+  };
+}
+
+export async function loadDefaultSkillFiles(): Promise<DefaultSkillFile[]> {
+  const sourceRoot = join(moduleDir, "..", "templates", "skills");
+  const sourceFiles = await listFiles(sourceRoot);
+
+  return Promise.all(
+    sourceFiles.map(async (sourcePath) => ({
+      path: join("skills", relative(sourceRoot, sourcePath)).replaceAll("\\", "/"),
+      contents: await readFile(sourcePath, "utf8"),
+    })),
+  );
+}
+
+async function listFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const path = join(directory, entry.name);
+
+      if (entry.isDirectory()) {
+        return listFiles(path);
+      }
+
+      return entry.isFile() ? [path] : [];
+    }),
+  );
+
+  return files.flat().sort();
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/runtime/targets/cloudflare/build.ts

@@ -36,6 +36,7 @@ export type AgentManifest = {
   prompt: SharedAgentManifest["prompt"];
   secrets: SharedAgentManifest["secrets"];
   tools: SharedAgentManifest["tools"];
+  integrations: SharedAgentManifest["integrations"];
   channels: SharedAgentManifest["channels"];
   transcription: SharedAgentManifest["transcription"];
   knowledge: SharedAgentManifest["knowledge"];
@@ -198,6 +199,7 @@ function buildManifest(
     prompt: shared.prompt,
     secrets: shared.secrets,
     tools: shared.tools,
+    integrations: shared.integrations,
     channels: shared.channels,
     transcription: shared.transcription,
     knowledge: shared.knowledge,
@@ -383,6 +385,23 @@ export function defineTool(tool) {
   return tool;
 }
 
+export function composioManaged(input) {
+  const name = normalizeIntegrationName(input.name ?? "composio", "composio integration name");
+  const toolkits = normalizeToolkitList(input.toolkits, "composioManaged.toolkits");
+  const tools = input.tools ? normalizeComposioToolMap(input.tools, toolkits) : undefined;
+  const tags = input.tags ? normalizeIntegrationTags(input.tags) : undefined;
+
+  return {
+    type: "composio",
+    provider: "composio",
+    mode: "managed",
+    name,
+    toolkits,
+    ...(tools ? { tools } : {}),
+    ...(tags ? { tags } : {}),
+  };
+}
+
 export function websiteChannel(input) {
   return {
     type: "website",
@@ -440,6 +459,105 @@ function normalizeChannelSecrets(secrets, context) {
   return Array.from(uniqueSecrets).sort();
 }
 
+function normalizeIntegrationName(value, context) {
+  const name = value.trim();
+
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error(\`\${context} must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.\`);
+  }
+
+  return name;
+}
+
+function normalizeToolkitList(values, context) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error(\`\${context} must include at least one toolkit slug.\`);
+  }
+
+  const toolkits = new Set();
+
+  for (const value of values) {
+    if (typeof value !== "string") {
+      throw new Error(\`\${context} entries must be toolkit slug strings.\`);
+    }
+
+    const toolkit = value.trim().toLowerCase();
+
+    if (!/^[a-z][a-z0-9_-]*$/.test(toolkit)) {
+      throw new Error(\`\${context} entries must start with a letter and contain only letters, numbers, underscores, and hyphens.\`);
+    }
+
+    toolkits.add(toolkit);
+  }
+
+  return Array.from(toolkits).sort();
+}
+
+function normalizeComposioToolMap(values, toolkits) {
+  const toolkitSet = new Set(toolkits);
+  const normalized = {};
+
+  for (const [rawToolkit, rawTools] of Object.entries(values)) {
+    const toolkit = rawToolkit.trim().toLowerCase();
+
+    if (!toolkitSet.has(toolkit)) {
+      throw new Error(\`composioManaged.tools.\${rawToolkit} must reference a toolkit listed in composioManaged.toolkits.\`);
+    }
+
+    if (!Array.isArray(rawTools) || rawTools.length === 0) {
+      throw new Error(\`composioManaged.tools.\${rawToolkit} must include at least one Composio action slug.\`);
+    }
+
+    const tools = new Set();
+
+    for (const rawTool of rawTools) {
+      if (typeof rawTool !== "string") {
+        throw new Error(\`composioManaged.tools.\${rawToolkit} entries must be Composio action slug strings.\`);
+      }
+
+      const tool = rawTool.trim().toUpperCase();
+
+      if (!/^[A-Z][A-Z0-9_]*$/.test(tool)) {
+        throw new Error(\`composioManaged.tools.\${rawToolkit} entries must be uppercase Composio action slugs.\`);
+      }
+
+      tools.add(tool);
+    }
+
+    normalized[toolkit] = Array.from(tools).sort();
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function normalizeIntegrationTags(tags) {
+  const normalized = {};
+
+  if (tags.enable !== undefined) {
+    normalized.enable = normalizeTagList(tags.enable, "composioManaged.tags.enable");
+  }
+
+  if (tags.disable !== undefined) {
+    normalized.disable = normalizeTagList(tags.disable, "composioManaged.tags.disable");
+  }
+
+  return normalized;
+}
+
+function normalizeTagList(values, context) {
+  if (!Array.isArray(values)) {
+    throw new Error(\`\${context} must be an array of tag strings.\`);
+  }
+
+  return Array.from(new Set(values.map((value) => {
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new Error(\`\${context} entries must be non-empty strings.\`);
+    }
+
+    return value.trim();
+  }))).sort();
+}
+
 function normalizeChannelBuffer(input, context) {
   if (input.mode === "off") {
     return { mode: "off" };
@@ -542,17 +660,18 @@ function renderCloudflareWorker(input: { manifest: AgentManifest; instructions:
   const instructionsJson = JSON.stringify(input.instructions);
   const configImportPath = JSON.stringify(input.configPath);
   const providerImportPath = JSON.stringify(resolve(moduleDir, "../../../providers/index.ts"));
+  const composioIntegrationImportPath = JSON.stringify(resolve(moduleDir, "../../integrations/composio.ts"));
   const promptContextImportPath = JSON.stringify(resolve(moduleDir, "../../prompt-context.ts"));
 
   return `import { DurableObject } from "cloudflare:workers";
 import agentConfig from ${configImportPath};
 import { getProviderAdapter } from ${providerImportPath};
+import { MANAGED_COMPOSIO_USER_ID_BINDING, createManagedComposioTools } from ${composioIntegrationImportPath};
 import { appendRuntimePromptContext, buildRuntimeClockContext } from ${promptContextImportPath};
 
 const manifest = ${manifestJson};
 const instructions = ${instructionsJson};
 const hostedKnowledgeTool = manifest.knowledge.enabled ? createHostedKnowledgeSearchTool() : null;
-const hostedTools = hostedKnowledgeTool ? [hostedKnowledgeTool, ...(agentConfig.tools ?? [])] : (agentConfig.tools ?? []);
 const DEFAULT_TOOL_TIMEOUT_MS = 30000;
 
 export class AgentKitConversationStore extends DurableObject {
@@ -721,13 +840,16 @@ export default {
         return auth;
       }
 
+      const hostedTools = createHostedTools(env);
+
       return Response.json({
         agent: manifest.name,
         runtime: manifest.runtime,
         target: manifest.target,
         provider: manifest.provider,
         prompt: manifest.prompt,
-        tools: manifest.tools.map((tool) => tool.name),
+        tools: hostedTools.map((tool) => tool.name),
+        integrations: hostedIntegrations(env),
         channels: manifest.channels.map((channel) => ({
           name: channel.name,
           type: channel.type,
@@ -1129,6 +1251,7 @@ function isRecord(value) {
 
 async function callHostedProvider(env, messages, signal) {
   const adapter = getProviderAdapter(manifest.provider);
+  const hostedTools = createHostedTools(env);
   const clock = buildRuntimeClockContext({
     timeZone: manifest.timeZone,
     env,
@@ -1626,18 +1749,49 @@ function inspectHostedDatabase() {
 }
 
 function hostedManagedSecrets() {
-  if (manifest.storage.database.driver !== "turso") {
-    return [];
+  const secrets = [];
+
+  if (manifest.storage.database.driver === "turso") {
+    secrets.push("TURSO_AUTH_TOKEN", "TURSO_DATABASE_URL");
   }
 
-  return ["TURSO_AUTH_TOKEN", "TURSO_DATABASE_URL"];
+  if (manifest.integrations.some((integration) => integration.provider === "composio" && integration.mode === "managed")) {
+    secrets.push("COMPOSIO_API_KEY");
+  }
+
+  return secrets.sort();
+}
+
+function createHostedTools(env) {
+  return [
+    ...(hostedKnowledgeTool ? [hostedKnowledgeTool] : []),
+    ...createManagedComposioTools(agentConfig, { userId: env[MANAGED_COMPOSIO_USER_ID_BINDING] }),
+    ...(agentConfig.tools ?? []),
+  ];
+}
+
+function hostedIntegrations(env) {
+  const userId = env[MANAGED_COMPOSIO_USER_ID_BINDING];
+
+  if (!userId) {
+    return manifest.integrations;
+  }
+
+  return manifest.integrations.map((integration) =>
+    integration.provider === "composio" && integration.mode === "managed"
+      ? { ...integration, userId }
+      : integration,
+  );
 }
 
 function createHostedProviderToolRuntime(env, signal, clock) {
+  const hostedTools = createHostedTools(env);
+
   return {
     definitions: hostedTools,
     execute(request) {
       return executeHostedTool({
+        tools: hostedTools,
         name: request.name,
         input: request.input,
         env,
@@ -1650,6 +1804,7 @@ function createHostedProviderToolRuntime(env, signal, clock) {
 }
 
 async function executeHostedTool(request) {
+  const hostedTools = request.tools ?? createHostedTools(request.env);
   const tool = hostedTools.find((candidate) => candidate.name === request.name);
   const id = crypto.randomUUID();
 

package/src/runtime/tool-runner.ts

@@ -2,6 +2,7 @@ import { loadAgentCapsule } from "./config";
 import { openPreparedCapsuleStore } from "./database";
 import { loadCapsuleEnv } from "./env";
 import { isAgentKitError } from "./errors";
+import { createManagedComposioTools } from "./integrations/composio";
 import { buildRuntimeClockContext } from "./prompt-context";
 import { createToolRuntime, type ToolCallResult } from "./tools";
 
@@ -26,7 +27,7 @@ export async function runToolFromCwd(cwd: string, options: RunToolOptions): Prom
     model: capsule.config.provider.model,
   });
   const toolRuntime = createToolRuntime({
-    tools: capsule.config.tools ?? [],
+    tools: [...createManagedComposioTools(capsule.config), ...(capsule.config.tools ?? [])],
     store,
     runId: run.id,
     conversationId: conversation.id,

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

@@ -19,6 +19,7 @@ Use this first inside an AgentKit Agent Capsule.
 - Build or reshape the agent from the owner's brief: `skills/agentkit-build-agent/SKILL.md`
 - Edit prompts: `skills/agentkit-prompts/SKILL.md`
 - Add actions or external data: `skills/agentkit-tools/SKILL.md`
+- Add AgentKit-managed integrations such as managed Composio: `skills/agentkit-integrations/SKILL.md`
 - Add database tables or database-backed tools: `skills/agentkit-database/SKILL.md`
 - Add docs, FAQs, prices, policies, or CSV facts: `skills/agentkit-knowledge/SKILL.md`
 - Switch from `test/fake` to a real model provider: `skills/agentkit-provider/SKILL.md`

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

@@ -80,6 +80,8 @@ npm run agentkit -- channels connect telegram support-telegram
 npm run agentkit -- channels add whatsapp support-whatsapp --provider zapster
 npm run agentkit -- channels doctor support-telegram
 npm run agentkit -- channels test support-telegram --message "hello"
+npm run agentkit -- channels test-audio support-telegram --fixture voice-note
+npm run agentkit -- transcribe smoke --provider groq
 npm run agentkit -- channels deliveries list support-telegram
 ```
 

package/src/templates/skills/agentkit-channels/references/channel-debugging.md

@@ -7,6 +7,8 @@ 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 deliveries list <name> --since 24h
 agentkit channels deliveries show <delivery-id>
 agentkit channels buffers list <name>
@@ -42,7 +44,7 @@ skipped
 
 Common errors:
 
-- `channel_not_found`: webhook URL points to an unknown channel.
+- `channel_not_found`: webhook URL points to an unknown channel. `channels test` is the official synthetic smoke and should resolve the current `.agentkit/deploy.json` channel.
 - `channel_secret_missing`: required hosted secret is not set.
 - `channel_signature_invalid`: webhook secret, token, or origin header mismatch.
 - `channel_payload_invalid`: malformed or unsupported provider payload.

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

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

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

@@ -18,6 +18,7 @@ Use this when the owner asks to prepare, test, or run hosted deploy.
 
 ```sh
 npm run typecheck
+npm run agentkit -- skills status
 npm run agentkit -- inspect
 npm run agentkit -- db migrate
 npm run chat -- --message "hello"
@@ -41,4 +42,3 @@ Open the printed `Chat:` URL and report it to the owner.
 ## Production Handoff
 
 Report changed files, required env/secret names, database schema changes, deploy order, smoke checks, rollback concerns, and whether the provider was still `test/fake`.
-