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

package/src/index.ts

@@ -145,6 +145,32 @@ export type WhatsappChannelConfig = {
 
 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;
+  confirmExternalWrites?: boolean;
+};
+
+export type ComposioManagedIntegration = {
+  type: "composio";
+  provider: "composio";
+  mode: "managed";
+  name: string;
+  toolkits: string[];
+  tools?: Record<string, string[]>;
+  tags?: IntegrationTagsConfig;
+  confirmExternalWrites?: boolean;
+};
+
+export type AgentIntegration = ComposioManagedIntegration;
+
 export type AgentDatabaseConfig =
   | {
       driver: "none";
@@ -316,6 +342,7 @@ export type AgentConfig = {
   instructions: string;
   secrets: string[];
   tools?: AgentTool[];
+  integrations?: AgentIntegration[];
   channels?: AgentChannel[];
   transcription?: AgentTranscriptionConfig;
   knowledge?: AgentKnowledgeConfig;
@@ -338,6 +365,25 @@ 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;
+  const confirmExternalWrites = input.confirmExternalWrites;
+
+  return {
+    type: "composio",
+    provider: "composio",
+    mode: "managed",
+    name,
+    toolkits,
+    ...(tools ? { tools } : {}),
+    ...(tags ? { tags } : {}),
+    ...(confirmExternalWrites === undefined ? {} : { confirmExternalWrites }),
+  };
+}
+
 export function websiteChannel(input: WebsiteChannelInput): WebsiteChannelConfig {
   return {
     type: "website",
@@ -404,6 +450,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" };

package/src/runtime/chat.ts

@@ -7,6 +7,7 @@ import { loadAgentCapsule } from "./config";
 import { openPreparedCapsuleStore } from "./database";
 import { loadCapsuleEnv } from "./env";
 import { AgentKitError, isAgentKitError } from "./errors";
+import { createManagedComposioTools } from "./integrations/composio";
 import { syncConfiguredKnowledgeSources } from "./knowledge/ingest";
 import { appendKnowledgePromptPolicy } from "./knowledge/prompt-policy";
 import { createKnowledgeSearchTool } from "./knowledge/tool";
@@ -145,7 +146,7 @@ export async function runAgentMessage(
 }
 
 function withKnowledgeTools(capsule: LoadedAgentCapsule): NonNullable<LoadedAgentCapsule["config"]["tools"]> {
-  const tools = [...(capsule.config.tools ?? [])];
+  const tools = [...createManagedComposioTools(capsule.config), ...(capsule.config.tools ?? [])];
   const knowledgeTool = createKnowledgeSearchTool(capsule);
 
   if (knowledgeTool) {

package/src/runtime/config.ts

@@ -16,9 +16,11 @@ import type {
   TelegramAllowedUpdate,
   AgentKnowledgeEmbeddingProvider,
   ChannelBufferMode,
+  AgentIntegration,
   ChannelAudioMode,
   TranscriptionProviderName,
 } from "../index";
+import { MANAGED_COMPOSIO_TOOL_NAME } from "./integrations/composio";
 import { AgentKitError } from "./errors";
 import { isValidTimeZone } from "./prompt-context";
 
@@ -35,6 +37,9 @@ const TELEGRAM_ALLOWED_UPDATES = new Set<TelegramAllowedUpdate>(["message"]);
 const KNOWLEDGE_EMBEDDING_PROVIDERS = new Set<AgentKnowledgeEmbeddingProvider>(["none", "test", "openai"]);
 const TRANSCRIPTION_PROVIDERS = new Set<TranscriptionProviderName>(["test", "openai", "groq"]);
 const CHANNEL_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const INTEGRATION_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const COMPOSIO_TOOLKIT_PATTERN = /^[a-z][a-z0-9_-]*$/;
+const COMPOSIO_TOOL_SLUG_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 const SECRET_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 let configImportNonce = 0;
@@ -234,6 +239,7 @@ function validateAgentConfig(value: unknown): asserts value is AgentConfig {
     }
   }
 
+  validateIntegrations(value.integrations, value.runtime as AgentRuntime, value.tools);
   validateTranscriptionConfig(value.transcription);
   validateChannels(value.channels, value.runtime as AgentRuntime, Boolean(value.transcription));
   validateKnowledgeConfig(value.knowledge);
@@ -258,6 +264,133 @@ function validateAgentConfig(value: unknown): asserts value is AgentConfig {
   validateFilesConfig(value.storage.files);
 }
 
+function validateIntegrations(
+  value: unknown,
+  runtime: AgentRuntime,
+  tools: AgentConfig["tools"] = [],
+): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw invalidConfig("integrations must be an array when provided.");
+  }
+
+  if (value.length > 0 && runtime !== "edge") {
+    throw invalidConfig('managed integrations require runtime: "edge". Use BYO defineTool wrappers for local-only integrations.');
+  }
+
+  let composioCount = 0;
+
+  for (const [index, integration] of value.entries()) {
+    if (!isRecord(integration)) {
+      throw invalidConfig(`integrations[${index}] must be an object.`);
+    }
+
+    if (integration.provider !== "composio" || integration.type !== "composio" || integration.mode !== "managed") {
+      throw invalidConfig(`integrations[${index}] must be composioManaged({...}) or { type: "composio", provider: "composio", mode: "managed", ... }.`);
+    }
+
+    composioCount += 1;
+    validateComposioManagedIntegration(integration as unknown as AgentIntegration, index);
+  }
+
+  if (composioCount > 1) {
+    throw invalidConfig("Only one managed Composio integration is supported per agent.");
+  }
+
+  const hasExplicitComposioTools = value.some(
+    (integration) => isRecord(integration) && integration.provider === "composio" && isRecord(integration.tools),
+  );
+
+  if (hasExplicitComposioTools && tools.some((tool) => isRecord(tool) && tool.name === MANAGED_COMPOSIO_TOOL_NAME)) {
+    throw invalidConfig(`tools must not declare reserved managed Composio tool name "${MANAGED_COMPOSIO_TOOL_NAME}".`);
+  }
+}
+
+function validateComposioManagedIntegration(value: AgentIntegration, index: number): void {
+  expectString(value.name, `integrations[${index}].name`);
+
+  if (!INTEGRATION_NAME_PATTERN.test(value.name)) {
+    throw invalidConfig(`integrations[${index}].name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.`);
+  }
+
+  if (!Array.isArray(value.toolkits) || value.toolkits.length === 0) {
+    throw invalidConfig(`integrations[${index}].toolkits must include at least one Composio toolkit slug.`);
+  }
+
+  const toolkits = new Set<string>();
+
+  for (const [toolkitIndex, toolkit] of value.toolkits.entries()) {
+    expectString(toolkit, `integrations[${index}].toolkits[${toolkitIndex}]`);
+
+    if (!COMPOSIO_TOOLKIT_PATTERN.test(toolkit)) {
+      throw invalidConfig(`integrations[${index}].toolkits[${toolkitIndex}] must be a lowercase Composio toolkit slug.`);
+    }
+
+    if (toolkits.has(toolkit)) {
+      throw invalidConfig(`integrations[${index}].toolkits must not contain duplicates.`);
+    }
+
+    toolkits.add(toolkit);
+  }
+
+  if (value.tools !== undefined) {
+    if (!isRecord(value.tools)) {
+      throw invalidConfig(`integrations[${index}].tools must be an object when provided.`);
+    }
+
+    for (const [toolkit, tools] of Object.entries(value.tools)) {
+      if (!toolkits.has(toolkit)) {
+        throw invalidConfig(`integrations[${index}].tools.${toolkit} must reference a toolkit listed in integrations[${index}].toolkits.`);
+      }
+
+      if (!Array.isArray(tools) || tools.length === 0) {
+        throw invalidConfig(`integrations[${index}].tools.${toolkit} must include at least one Composio action slug.`);
+      }
+
+      const seenTools = new Set<string>();
+
+      for (const [toolIndex, tool] of tools.entries()) {
+        expectString(tool, `integrations[${index}].tools.${toolkit}[${toolIndex}]`);
+
+        if (!COMPOSIO_TOOL_SLUG_PATTERN.test(tool)) {
+          throw invalidConfig(`integrations[${index}].tools.${toolkit}[${toolIndex}] must be an uppercase Composio action slug.`);
+        }
+
+        if (seenTools.has(tool)) {
+          throw invalidConfig(`integrations[${index}].tools.${toolkit} must not contain duplicates.`);
+        }
+
+        seenTools.add(tool);
+      }
+    }
+  }
+
+  if (value.tags !== undefined) {
+    validateIntegrationTags(value.tags, `integrations[${index}].tags`);
+  }
+
+  if (value.confirmExternalWrites !== undefined && typeof value.confirmExternalWrites !== "boolean") {
+    throw invalidConfig(`integrations[${index}].confirmExternalWrites must be a boolean when provided.`);
+  }
+}
+
+function validateIntegrationTags(value: unknown, label: string): void {
+  if (!isRecord(value)) {
+    throw invalidConfig(`${label} must be an object when provided.`);
+  }
+
+  if (value.enable !== undefined) {
+    expectStringArray(value.enable, `${label}.enable`);
+  }
+
+  if (value.disable !== undefined) {
+    expectStringArray(value.disable, `${label}.disable`);
+  }
+}
+
 function validateTranscriptionConfig(value: unknown): void {
   if (value === undefined) {
     return;

package/src/runtime/core/manifest.ts

@@ -2,6 +2,11 @@ import { relative, resolve } from "node:path";
 
 import type { AgentConfig, AgentTool } from "../../index";
 import type { LoadedAgentCapsule } from "../config";
+import {
+  createManagedComposioTools,
+  managedComposioRequiredSecrets,
+  resolveManagedComposioIntegrations,
+} from "../integrations/composio";
 import { resolveKnowledgeConfig } from "../knowledge/config";
 import { KNOWLEDGE_SEARCH_TOOL_NAME } from "../knowledge/tool";
 import { resolveTranscriptionConfig } from "../transcription";
@@ -28,6 +33,15 @@ export type SharedAgentManifest = {
     permissions: string[];
     timeoutMs: number | null;
   }>;
+  integrations: Array<{
+    name: string;
+    provider: "composio";
+    mode: "managed";
+    toolkits: string[];
+    tools: string[];
+    userId: string;
+    confirmExternalWrites: boolean;
+  }>;
   channels: NonNullable<AgentConfig["channels"]>;
   transcription: {
     enabled: boolean;
@@ -94,6 +108,8 @@ export function buildSharedAgentManifest(
   const database = buildDatabaseManifest(capsule, options.databaseSchema ?? null);
   const files = buildFilesManifest(capsule);
   const knowledge = resolveKnowledgeConfig(capsule.config);
+  const integrationTools = createManagedComposioTools(capsule.config);
+  const tools = [...integrationTools, ...(capsule.config.tools ?? [])];
   const transcription = resolveTranscriptionConfig(capsule.config.transcription);
 
   requiredSecrets.add("AGENTKIT_PRIVATE_TOKEN");
@@ -119,7 +135,11 @@ export function buildSharedAgentManifest(
     requiredSecrets.add(transcription.secret);
   }
 
-  for (const tool of capsule.config.tools ?? []) {
+  for (const secret of managedComposioRequiredSecrets(capsule.config)) {
+    requiredSecrets.add(secret);
+  }
+
+  for (const tool of tools) {
     for (const secret of tool.secrets ?? []) {
       requiredSecrets.add(secret);
     }
@@ -139,7 +159,7 @@ export function buildSharedAgentManifest(
     timeZone: capsule.config.timeZone ?? null,
     prompt: toCapsulePath(capsule, capsule.instructionsPath),
     secrets: Array.from(requiredSecrets).sort(),
-    tools: (capsule.config.tools ?? []).map((tool) => ({
+    tools: tools.map((tool) => ({
       name: tool.name,
       description: tool.description,
       inputSchema: tool.inputSchema,
@@ -148,6 +168,15 @@ export function buildSharedAgentManifest(
       permissions: [...(tool.permissions ?? [])].sort(),
       timeoutMs: tool.timeoutMs ?? null,
     })),
+    integrations: resolveManagedComposioIntegrations(capsule.config).map((integration) => ({
+      name: integration.name,
+      provider: integration.provider,
+      mode: integration.mode,
+      toolkits: integration.toolkits,
+      tools: integration.allowedTools,
+      userId: integration.userId,
+      confirmExternalWrites: integration.confirmExternalWrites !== false,
+    })),
     channels: capsule.config.channels ?? [],
     transcription: {
       enabled: transcription.enabled,

package/src/runtime/deploy-readiness.ts

@@ -3,6 +3,10 @@ import { createHash } from "node:crypto";
 import { loadAgentCapsule } from "./config";
 import { buildSharedAgentManifest } from "./core/manifest";
 import { listCapsuleEnv } from "./env";
+import {
+  MANAGED_COMPOSIO_API_KEY_SECRET,
+  resolveManagedComposioIntegrations,
+} from "./integrations/composio";
 
 export type DeployReadinessSecretSource = {
   dotenv: boolean;
@@ -30,6 +34,14 @@ export type DeployReadinessContext = {
     embeddingProvider: string;
     databaseDriver: "none" | "turso";
   };
+  integrations: {
+    managedComposio: {
+      enabled: boolean;
+      toolkits: string[];
+      toolCount: number;
+      userId: string | null;
+    };
+  };
 };
 
 export async function loadDeployReadinessContext(
@@ -38,6 +50,7 @@ export async function loadDeployReadinessContext(
 ): Promise<DeployReadinessContext> {
   const capsule = await loadAgentCapsule(cwd);
   const manifest = buildSharedAgentManifest(capsule);
+  const managedComposio = resolveManagedComposioIntegrations(capsule.config)[0];
   const dotenvNames = new Set(await listCapsuleEnv(capsule.root));
   const requiredSecrets = manifest.secrets;
   const localSecrets: Record<string, DeployReadinessSecretSource> = {};
@@ -57,6 +70,7 @@ export async function loadDeployReadinessContext(
     isAgentKitManagedDeploySecret(name, {
       accessMode: capsule.config.access.mode,
       databaseDriver: manifest.storage.database.driver,
+      managedComposioEnabled: Boolean(managedComposio),
     }),
   );
   const managed = new Set(agentKitManagedSecrets);
@@ -82,6 +96,14 @@ export async function loadDeployReadinessContext(
       embeddingProvider: manifest.knowledge.embedding.provider,
       databaseDriver: manifest.storage.database.driver,
     },
+    integrations: {
+      managedComposio: {
+        enabled: Boolean(managedComposio),
+        toolkits: managedComposio?.toolkits ?? [],
+        toolCount: managedComposio?.allowedTools.length ?? 0,
+        userId: managedComposio?.userId ?? null,
+      },
+    },
   };
 }
 
@@ -91,7 +113,11 @@ export function stableCloudProjectId(name: string, accountId?: string | null): s
 
 function isAgentKitManagedDeploySecret(
   name: string,
-  context: { accessMode: DeployReadinessContext["accessMode"]; databaseDriver: "none" | "turso" },
+  context: {
+    accessMode: DeployReadinessContext["accessMode"];
+    databaseDriver: "none" | "turso";
+    managedComposioEnabled: boolean;
+  },
 ): boolean {
   if (context.databaseDriver === "turso" && (name === "TURSO_DATABASE_URL" || name === "TURSO_AUTH_TOKEN")) {
     return true;
@@ -101,5 +127,9 @@ function isAgentKitManagedDeploySecret(
     return true;
   }
 
+  if (context.managedComposioEnabled && name === MANAGED_COMPOSIO_API_KEY_SECRET) {
+    return true;
+  }
+
   return false;
 }