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

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 {
@@ -612,6 +731,22 @@ export class AgentKitConversationStore extends DurableObject {
       return this.getMessages(url.searchParams.get("conversationId"));
     }
 
+    if (request.method === "GET" && url.pathname === "/conversations") {
+      return this.listConversations();
+    }
+
+    const conversationTraceMatch = url.pathname.match(/^\\/conversations\\/([^/]+)\\/trace$/);
+
+    if (request.method === "GET" && conversationTraceMatch) {
+      return this.getConversationTrace(decodeURIComponent(conversationTraceMatch[1] || ""));
+    }
+
+    const conversationMatch = url.pathname.match(/^\\/conversations\\/([^/]+)$/);
+
+    if (request.method === "GET" && conversationMatch) {
+      return this.getConversation(decodeURIComponent(conversationMatch[1] || ""));
+    }
+
     return Response.json({ error: { code: "not_found", message: "Unknown Durable Object route." } }, { status: 404 });
   }
 
@@ -635,6 +770,128 @@ export class AgentKitConversationStore extends DurableObject {
     });
   }
 
+  listConversations() {
+    const rows = this.sql.exec(\`
+      SELECT conversations.id, conversations.agent_name, conversations.title, conversations.created_at, conversations.updated_at, COUNT(messages.id) AS message_count
+      FROM conversations
+      LEFT JOIN messages ON messages.conversation_id = conversations.id
+      GROUP BY conversations.id, conversations.agent_name, conversations.title, conversations.created_at, conversations.updated_at
+      ORDER BY conversations.updated_at DESC
+    \`).toArray();
+
+    return Response.json({
+      conversations: rows.map((row) => ({
+        id: String(row.id),
+        agentName: String(row.agent_name),
+        title: row.title === null || row.title === undefined ? null : String(row.title),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        messageCount: Number(row.message_count || 0),
+      })),
+    });
+  }
+
+  getConversation(conversationId) {
+    const conversation = this.readConversation(conversationId);
+
+    if (!conversation) {
+      return Response.json(
+        { error: { code: "conversation_not_found", message: \`Conversation "\${conversationId}" was not found.\` } },
+        { status: 404 },
+      );
+    }
+
+    return Response.json(conversation);
+  }
+
+  getConversationTrace(conversationId) {
+    const conversation = this.readConversation(conversationId);
+
+    if (!conversation) {
+      return Response.json(
+        { error: { code: "conversation_not_found", message: \`Conversation "\${conversationId}" was not found.\` } },
+        { status: 404 },
+      );
+    }
+
+    const runs = this.sql.exec(
+      "SELECT id, conversation_id, provider, model, status, error_code, error_message, created_at, completed_at FROM runs WHERE conversation_id = ? ORDER BY rowid ASC",
+      conversationId,
+    ).toArray();
+
+    return Response.json({
+      ...conversation,
+      runs: runs.map((run) => ({
+        id: String(run.id),
+        conversationId: String(run.conversation_id),
+        provider: String(run.provider),
+        model: String(run.model),
+        status: String(run.status),
+        errorCode: run.error_code === null || run.error_code === undefined ? null : String(run.error_code),
+        errorMessage: run.error_message === null || run.error_message === undefined ? null : String(run.error_message),
+        startedAt: String(run.created_at),
+        completedAt: run.completed_at === null || run.completed_at === undefined ? null : String(run.completed_at),
+        toolCalls: this.readToolCalls(String(run.id)),
+      })),
+    });
+  }
+
+  readConversation(conversationId) {
+    if (!conversationId) {
+      return null;
+    }
+
+    const row = this.sql.exec(
+      "SELECT id, agent_name, title, created_at, updated_at FROM conversations WHERE id = ?",
+      conversationId,
+    ).one();
+
+    if (!row) {
+      return null;
+    }
+
+    const messages = this.sql.exec(
+      "SELECT id, conversation_id, role, content, created_at FROM messages WHERE conversation_id = ? ORDER BY rowid ASC",
+      conversationId,
+    ).toArray();
+
+    return {
+      id: String(row.id),
+      agentName: String(row.agent_name),
+      title: row.title === null || row.title === undefined ? null : String(row.title),
+      createdAt: String(row.created_at),
+      updatedAt: String(row.updated_at),
+      messages: messages.map((message) => ({
+        id: String(message.id),
+        conversationId: String(message.conversation_id),
+        role: String(message.role),
+        content: String(message.content),
+        createdAt: String(message.created_at),
+      })),
+    };
+  }
+
+  readToolCalls(runId) {
+    const rows = this.sql.exec(
+      "SELECT id, run_id, conversation_id, tool_name, visibility, status, input_json, output_json, error_message, created_at, completed_at FROM tool_calls WHERE run_id = ? ORDER BY rowid ASC",
+      runId,
+    ).toArray();
+
+    return rows.map((row) => ({
+      id: String(row.id),
+      runId: String(row.run_id),
+      conversationId: String(row.conversation_id),
+      name: String(row.tool_name),
+      visibility: String(row.visibility),
+      status: String(row.status),
+      input: parseStoredJson(row.input_json, {}),
+      output: row.output_json === null || row.output_json === undefined ? undefined : parseStoredJson(row.output_json, null),
+      errorMessage: row.error_message === null || row.error_message === undefined ? null : String(row.error_message),
+      createdAt: String(row.created_at),
+      completedAt: row.completed_at === null || row.completed_at === undefined ? null : String(row.completed_at),
+    }));
+  }
+
   persistMessages(input) {
     const now = new Date().toISOString();
     const conversationId = String(input.conversationId || crypto.randomUUID());
@@ -721,13 +978,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,
@@ -765,6 +1025,22 @@ export default {
       return handleChat(request, env);
     }
 
+    if (request.method === "GET" && (url.pathname === "/conversations" || url.pathname === "/v1/conversations")) {
+      return handleConversationRead(request, env, "list");
+    }
+
+    const conversationTraceMatch = url.pathname.match(/^\\/(?:v1\\/)?conversations\\/([^/]+)\\/trace$/);
+
+    if (request.method === "GET" && conversationTraceMatch) {
+      return handleConversationRead(request, env, "trace", decodeURIComponent(conversationTraceMatch[1] || ""));
+    }
+
+    const conversationMatch = url.pathname.match(/^\\/(?:v1\\/)?conversations\\/([^/]+)$/);
+
+    if (request.method === "GET" && conversationMatch) {
+      return handleConversationRead(request, env, "show", decodeURIComponent(conversationMatch[1] || ""));
+    }
+
     if (request.method === "POST" && url.pathname.startsWith("/tools/")) {
       return handleTool(request, env, decodeURIComponent(url.pathname.slice("/tools/".length)));
     }
@@ -1111,6 +1387,39 @@ async function handleChat(request, env) {
   });
 }
 
+async function handleConversationRead(request, env, action, conversationId) {
+  const auth = await authorizeChat(request, env, {});
+
+  if (auth) {
+    return auth;
+  }
+
+  if (!env.AGENTKIT_CONVERSATIONS) {
+    return Response.json({ error: { code: "conversations_not_configured", message: "Hosted conversation storage is not configured." } }, { status: 503 });
+  }
+
+  if (action === "list") {
+    const stub = hostedConversationStore(env);
+    return stub.fetch("https://agentkit.internal/conversations");
+  }
+
+  if (!conversationId) {
+    return Response.json({ error: { code: "validation_error", message: "Missing conversation id." } }, { status: 400 });
+  }
+
+  const stub = hostedConversationStore(env);
+  const suffix = action === "trace" ? "/trace" : "";
+  const path = \`/conversations/\${encodeURIComponent(conversationId)}\${suffix}\`;
+  const response = await stub.fetch(\`https://agentkit.internal\${path}\`);
+
+  if (response.status !== 404) {
+    return response;
+  }
+
+  const legacyStub = legacyConversationStore(env, conversationId);
+  return legacyStub.fetch(\`https://agentkit.internal\${path}\`);
+}
+
 function readChatMessage(body) {
   if (typeof body.message === "string") {
     return body.message.trim();
@@ -1129,6 +1438,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 +1936,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");
+  }
+
+  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 ["TURSO_AUTH_TOKEN", "TURSO_DATABASE_URL"];
+  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 +1991,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();
 
@@ -2121,8 +2463,7 @@ async function persist(env, input) {
     return {};
   }
 
-  const id = env.AGENTKIT_CONVERSATIONS.idFromName(input.conversationId);
-  const stub = env.AGENTKIT_CONVERSATIONS.get(id);
+  const stub = hostedConversationStore(env);
   const response = await stub.fetch("https://agentkit.internal/messages", {
     method: "POST",
     body: JSON.stringify(input),
@@ -2140,8 +2481,7 @@ async function loadConversationMessages(env, conversationId) {
     return [];
   }
 
-  const id = env.AGENTKIT_CONVERSATIONS.idFromName(conversationId);
-  const stub = env.AGENTKIT_CONVERSATIONS.get(id);
+  const stub = hostedConversationStore(env);
   const response = await stub.fetch(
     \`https://agentkit.internal/messages?conversationId=\${encodeURIComponent(conversationId)}\`,
   );
@@ -2151,7 +2491,7 @@ async function loadConversationMessages(env, conversationId) {
   }
 
   const payload = await response.json();
-  return Array.isArray(payload.messages)
+  const messages = Array.isArray(payload.messages)
     ? payload.messages.filter((message) =>
         message &&
         typeof message === "object" &&
@@ -2159,6 +2499,39 @@ async function loadConversationMessages(env, conversationId) {
         typeof message.content === "string"
       )
     : [];
+
+  if (messages.length > 0) {
+    return messages;
+  }
+
+  const legacyStub = legacyConversationStore(env, conversationId);
+  const legacyResponse = await legacyStub.fetch(
+    \`https://agentkit.internal/messages?conversationId=\${encodeURIComponent(conversationId)}\`,
+  );
+
+  if (!legacyResponse.ok) {
+    return [];
+  }
+
+  const legacyPayload = await legacyResponse.json();
+  return Array.isArray(legacyPayload.messages)
+    ? legacyPayload.messages.filter((message) =>
+        message &&
+        typeof message === "object" &&
+        (message.role === "user" || message.role === "assistant") &&
+        typeof message.content === "string"
+      )
+    : [];
+}
+
+function hostedConversationStore(env) {
+  const id = env.AGENTKIT_CONVERSATIONS.idFromName("agentkit-conversations");
+  return env.AGENTKIT_CONVERSATIONS.get(id);
+}
+
+function legacyConversationStore(env, conversationId) {
+  const id = env.AGENTKIT_CONVERSATIONS.idFromName(conversationId);
+  return env.AGENTKIT_CONVERSATIONS.get(id);
 }
 
 function normalizeConversationId(value) {
@@ -2435,6 +2808,18 @@ function titleFromMessage(content) {
   const compact = content.split(/\\r?\\n/, 1)[0].replace(/\\s+/g, " ").trim();
   return compact.length <= 80 ? compact : \`\${compact.slice(0, 77)}...\`;
 }
+
+function parseStoredJson(value, fallback) {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
 `;
 }
 

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.