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

package/src/cli/index.ts

@@ -22,6 +22,7 @@ import { runEvalsFromCwd, writeEvalFromConversation } from "../runtime/evals";
 import { findAgentKitDocs } from "../runtime/docs";
 import { listCapsuleEnv, setCapsuleEnv, unsetCapsuleEnv } from "../runtime/env";
 import { checkAgentSpec, initializeAgentSpec } from "../runtime/spec";
+import { checkDefaultSkillStatus, syncDefaultSkillFiles } from "../runtime/skills";
 import { initializeSyncScaffold, runCapsuleSync } from "../runtime/sync";
 import { runToolFromCwd } from "../runtime/tool-runner";
 import { startAgentDevServer } from "../runtime/dev-server";
@@ -67,6 +68,7 @@ import { renderCommandHelp, renderCommandReference, renderHelp } from "./help";
 import { runInheritedCommand, waitForShutdown } from "./process";
 import { handleChannelsCommand } from "./commands/channels";
 import { handleKnowledgeCommand } from "./commands/knowledge";
+import { handleTranscribeCommand } from "./commands/transcribe";
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
@@ -764,6 +766,110 @@ async function main() {
     return;
   }
 
+  if (args.command === "transcribe") {
+    await handleTranscribeCommand(args);
+    return;
+  }
+
+  if (args.command === "skills") {
+    const [subcommand] = args.positional;
+    const root = await findAgentCapsuleRoot(process.cwd());
+
+    if (subcommand === "status") {
+      const status = await checkDefaultSkillStatus(root);
+      printSkillStatus(status);
+      if (status.status !== "current") {
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (subcommand === "sync") {
+      const result = await syncDefaultSkillFiles(root);
+      console.log(`Synced ${result.files.length} AgentKit skill files.`);
+      console.log("Status: current");
+      return;
+    }
+
+    throw new Error("Usage: agentkit skills status | agentkit skills sync");
+  }
+
+  if (args.command === "integrations") {
+    const [subcommand, provider] = args.positional;
+
+    if (provider !== undefined && provider !== "composio") {
+      throw new Error("Usage: agentkit integrations status | connect composio [--toolkit <slug>] [--callback-url <url>] [--api <url>]");
+    }
+
+    const state = await requireLocalDeployState();
+    const apiUrl = await resolveCloudApiUrl(args.flags.api);
+
+    if (subcommand === "status") {
+      const payload = await cloudApiRequest(
+        apiUrl,
+        `/v1/deploys/${encodeURIComponent(state.deploy_id)}/integrations/composio/status`,
+        { method: "GET" },
+      );
+      printJson(payload);
+      return;
+    }
+
+    if (subcommand === "connect" && provider === "composio") {
+      const toolkit = parseOptionalStringFlag(
+        args.flags.toolkit,
+        "toolkit",
+        "agentkit integrations connect composio --toolkit <slug>",
+      );
+      const callbackUrl = parseOptionalStringFlag(
+        args.flags["callback-url"],
+        "callback-url",
+        "agentkit integrations connect composio --callback-url <url>",
+      );
+      const payload = (await cloudApiRequest(
+        apiUrl,
+        `/v1/deploys/${encodeURIComponent(state.deploy_id)}/integrations/composio/connect-link`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            ...(toolkit ? { toolkit } : {}),
+            ...(callbackUrl ? { callback_url: callbackUrl } : {}),
+          }),
+        },
+      )) as {
+        connect_link?: {
+          toolkit?: string;
+          user_id?: string;
+          redirect_url?: string;
+          expires_at?: string;
+          connected_account_id?: string;
+        };
+      };
+
+      const link = payload.connect_link;
+
+      if (!link?.redirect_url) {
+        throw new AgentKitError("integration_response_invalid", "AgentKit Cloud returned an invalid Composio connect-link payload.");
+      }
+
+      console.log("Composio connect link");
+      console.log(`Toolkit: ${link.toolkit ?? toolkit ?? "unknown"}`);
+      console.log(`User:    ${link.user_id ?? "unknown"}`);
+      console.log(`URL:     ${link.redirect_url}`);
+
+      if (link.expires_at) {
+        console.log(`Expires: ${link.expires_at}`);
+      }
+
+      if (link.connected_account_id) {
+        console.log(`Account: ${link.connected_account_id}`);
+      }
+
+      return;
+    }
+
+    throw new Error("Usage: agentkit integrations status | connect composio [--toolkit <slug>] [--callback-url <url>] [--api <url>]");
+  }
+
   if (args.command === "env") {
     const [subcommand, name, ...valueParts] = args.positional;
     const root = await findAgentCapsuleRoot(process.cwd());
@@ -1078,6 +1184,30 @@ function printJson(value: unknown): void {
   console.log(JSON.stringify(value, null, 2));
 }
 
+function printSkillStatus(status: Awaited<ReturnType<typeof checkDefaultSkillStatus>>): void {
+  console.log("AgentKit skills");
+  console.log(`Status: ${status.status}`);
+  console.log(`Checked: ${status.checked}`);
+
+  if (status.missing.length > 0) {
+    console.log(`Missing: ${status.missing.length}`);
+    for (const file of status.missing.slice(0, 10)) {
+      console.log(`  ${file}`);
+    }
+  }
+
+  if (status.outdated.length > 0) {
+    console.log(`Outdated: ${status.outdated.length}`);
+    for (const file of status.outdated.slice(0, 10)) {
+      console.log(`  ${file}`);
+    }
+  }
+
+  if (status.status !== "current") {
+    console.log("Run: npm run agentkit -- skills sync");
+  }
+}
+
 async function printJsonOrWrite(value: unknown, outFlag: string | boolean | undefined, usage: string): Promise<void> {
   const outPath = parseOptionalStringFlag(outFlag, "out", usage);
 

package/src/create-project.ts

@@ -1,10 +1,11 @@
 import { execFile } from "node:child_process";
-import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 
-import { getTemplate, type TemplateFile } from "./templates";
+import { loadDefaultSkillFiles } from "./runtime/skills";
+import { getTemplate } from "./templates";
 
 const execFileAsync = promisify(execFile);
 const moduleDir = dirname(fileURLToPath(import.meta.url));
@@ -129,35 +130,6 @@ async function resolveAgentKitDependency(): Promise<string> {
   return packageJson.version;
 }
 
-async function loadDefaultSkillFiles(): Promise<TemplateFile[]> {
-  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 directoryExists(path: string): Promise<boolean> {
   try {
     const result = await stat(path);

package/src/index.ts

@@ -6,6 +6,8 @@ export type ChannelType = "website" | "telegram" | "whatsapp";
 export type ChannelProvider = "agentkit" | "telegram" | "zapster" | "meta";
 export type WhatsappChannelProvider = "zapster" | "meta";
 export type TelegramAllowedUpdate = "message";
+export type ChannelAudioMode = "off" | "reject" | "transcribe";
+export type TranscriptionProviderName = "test" | "openai" | "groq";
 
 export type AgentProvider = {
   name: AgentProviderName;
@@ -39,6 +41,45 @@ export type ChannelBufferConfig =
       maxChars: number;
     };
 
+export type ChannelAudioInput = {
+  mode?: ChannelAudioMode;
+  fallbackMessage?: string;
+  maxDurationSeconds?: number;
+  maxBytes?: number;
+};
+
+export type ChannelAudioConfig =
+  | {
+      mode: "off";
+    }
+  | {
+      mode: "reject";
+      fallbackMessage: string;
+      maxDurationSeconds?: number;
+      maxBytes?: number;
+    }
+  | {
+      mode: "transcribe";
+      fallbackMessage: string;
+      maxDurationSeconds?: number;
+      maxBytes?: number;
+    };
+
+export type AgentTranscriptionLimits = {
+  maxDurationSeconds?: number;
+  maxBytes?: number;
+};
+
+export type AgentTranscriptionConfig = {
+  provider: TranscriptionProviderName;
+  model: string;
+  secret?: string;
+  language?: string;
+  prompt?: string;
+  limits?: AgentTranscriptionLimits;
+  rawAudioTtlSeconds?: number;
+};
+
 export type WebsiteChannelAccess = {
   mode: "token";
 };
@@ -49,6 +90,7 @@ export type WebsiteChannelInput = {
   secrets?: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
+  audio?: ChannelAudioInput;
 };
 
 export type WebsiteChannelConfig = {
@@ -59,6 +101,7 @@ export type WebsiteChannelConfig = {
   secrets: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
+  audio?: ChannelAudioConfig;
 };
 
 export type TelegramChannelInput = {
@@ -67,6 +110,7 @@ export type TelegramChannelInput = {
   allowedUpdates?: TelegramAllowedUpdate[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
+  audio?: ChannelAudioInput;
 };
 
 export type TelegramChannelConfig = {
@@ -77,6 +121,7 @@ export type TelegramChannelConfig = {
   allowedUpdates: TelegramAllowedUpdate[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
+  audio?: ChannelAudioConfig;
 };
 
 export type WhatsappChannelInput = {
@@ -85,6 +130,7 @@ export type WhatsappChannelInput = {
   secrets?: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
+  audio?: ChannelAudioInput;
 };
 
 export type WhatsappChannelConfig = {
@@ -94,10 +140,35 @@ export type WhatsappChannelConfig = {
   secrets: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
+  audio?: ChannelAudioConfig;
 };
 
 export type AgentChannel = WebsiteChannelConfig | TelegramChannelConfig | WhatsappChannelConfig;
 
+export type IntegrationTagsConfig = {
+  enable?: string[];
+  disable?: string[];
+};
+
+export type ComposioManagedIntegrationInput = {
+  name?: string;
+  toolkits: string[];
+  tools?: Record<string, string[]>;
+  tags?: IntegrationTagsConfig;
+};
+
+export type ComposioManagedIntegration = {
+  type: "composio";
+  provider: "composio";
+  mode: "managed";
+  name: string;
+  toolkits: string[];
+  tools?: Record<string, string[]>;
+  tags?: IntegrationTagsConfig;
+};
+
+export type AgentIntegration = ComposioManagedIntegration;
+
 export type AgentDatabaseConfig =
   | {
       driver: "none";
@@ -269,7 +340,9 @@ export type AgentConfig = {
   instructions: string;
   secrets: string[];
   tools?: AgentTool[];
+  integrations?: AgentIntegration[];
   channels?: AgentChannel[];
+  transcription?: AgentTranscriptionConfig;
   knowledge?: AgentKnowledgeConfig;
   access: {
     mode: AccessMode;
@@ -290,6 +363,23 @@ export function defineTool<Input = unknown, Output = unknown>(tool: AgentTool<In
   return tool;
 }
 
+export function composioManaged(input: ComposioManagedIntegrationInput): ComposioManagedIntegration {
+  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: WebsiteChannelInput): WebsiteChannelConfig {
   return {
     type: "website",
@@ -299,6 +389,7 @@ export function websiteChannel(input: WebsiteChannelInput): WebsiteChannelConfig
     secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"], "website channel"),
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "website channel") } : {}),
+    ...(input.audio ? { audio: normalizeChannelAudio(input.audio, "website channel") } : {}),
   };
 }
 
@@ -314,6 +405,7 @@ export function telegramChannel(input: TelegramChannelInput): TelegramChannelCon
     allowedUpdates: input.allowedUpdates ?? ["message"],
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "telegram channel") } : {}),
+    ...(input.audio ? { audio: normalizeChannelAudio(input.audio, "telegram channel") } : {}),
   };
 }
 
@@ -328,6 +420,7 @@ export function whatsappChannel(input: WhatsappChannelInput): WhatsappChannelCon
     ),
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, `${input.provider} whatsapp channel`) } : {}),
+    ...(input.audio ? { audio: normalizeChannelAudio(input.audio, `${input.provider} whatsapp channel`) } : {}),
   };
 }
 
@@ -353,6 +446,109 @@ function normalizeChannelSecrets(secrets: string[], context: string): string[] {
   return Array.from(uniqueSecrets).sort();
 }
 
+function normalizeIntegrationName(value: string, context: string): string {
+  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: string[], context: string): string[] {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error(`${context} must include at least one toolkit slug.`);
+  }
+
+  const toolkits = new Set<string>();
+
+  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: Record<string, string[]>, toolkits: string[]): Record<string, string[]> | undefined {
+  const toolkitSet = new Set(toolkits);
+  const normalized: Record<string, string[]> = {};
+
+  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<string>();
+
+    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: IntegrationTagsConfig): IntegrationTagsConfig {
+  const normalized: IntegrationTagsConfig = {};
+
+  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: string[], context: string): string[] {
+  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: ChannelBufferInput, context: string): ChannelBufferConfig {
   if (input.mode === "off") {
     return { mode: "off" };
@@ -382,6 +578,33 @@ function normalizeChannelBuffer(input: ChannelBufferInput, context: string): Cha
   return buffer;
 }
 
+function normalizeChannelAudio(input: ChannelAudioInput, context: string): ChannelAudioConfig {
+  const mode = input.mode ?? "transcribe";
+
+  if (mode !== "off" && mode !== "reject" && mode !== "transcribe") {
+    throw new Error(`${context} audio.mode must be "off", "reject", or "transcribe".`);
+  }
+
+  if (mode === "off") {
+    return { mode: "off" };
+  }
+
+  if (input.maxDurationSeconds !== undefined) {
+    validatePositiveInteger(input.maxDurationSeconds, `${context} audio.maxDurationSeconds`);
+  }
+
+  if (input.maxBytes !== undefined) {
+    validatePositiveInteger(input.maxBytes, `${context} audio.maxBytes`);
+  }
+
+  return {
+    mode,
+    fallbackMessage: input.fallbackMessage ?? "I received an audio message, but I could not transcribe it. Please send the message as text.",
+    ...(input.maxDurationSeconds !== undefined ? { maxDurationSeconds: input.maxDurationSeconds } : {}),
+    ...(input.maxBytes !== undefined ? { maxBytes: input.maxBytes } : {}),
+  };
+}
+
 function validatePositiveInteger(value: number, field: string): void {
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error(`${field} must be a positive integer.`);
@@ -413,10 +636,13 @@ export { AgentKitError } from "./runtime/errors";
 export type {
   ChannelAdapter,
   ChannelAdapterId,
+  ChannelAudioAttachment,
   ChannelDeliveryDirection,
   ChannelDeliveryState,
   ChannelEventKind,
   ChannelExternalIdentity,
+  ChannelMediaDownloadInput,
+  ChannelMediaDownloadResult,
   ChannelMessageContentType,
   ChannelMessageRole,
   ChannelSendInput,
@@ -429,3 +655,8 @@ export type {
   WebhookVerificationInput,
   WebhookVerificationResult,
 } from "./runtime/channels";
+export type {
+  TranscriptionAdapter,
+  TranscriptionInput,
+  TranscriptionResult,
+} from "./runtime/transcription";

package/src/runtime/channel-test-harness.ts

@@ -8,9 +8,11 @@ import type { NormalizedChannelEvent, RawWebhookEvent } from "./channels";
 export type ChannelFixtureName =
   | "website-message"
   | "telegram-message"
+  | "telegram-audio-message"
   | "telegram-duplicate-message"
   | "telegram-malformed-payload"
   | "zapster-message"
+  | "zapster-audio-message"
   | "zapster-duplicate-message"
   | "zapster-unsupported-media";