@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/runtime/integrations/composio.ts

@@ -0,0 +1,423 @@
+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>;
+  confirmed?: boolean;
+};
+
+type ManagedComposioToolOutput = {
+  successful: boolean;
+  data: unknown;
+  error: unknown;
+  logId: string | null;
+  toolkit: string;
+  toolSlug: string;
+  userId: string;
+};
+
+type ComposioActionGuide = {
+  summary: string;
+  argumentNotes: string[];
+  dangerousDefaults?: string[];
+  examples?: Array<Record<string, unknown>>;
+};
+
+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.",
+        integration.confirmExternalWrites === false
+          ? "External write confirmation is disabled for this integration by agentkit.config.ts."
+          : "For write actions, pass confirmed: true only after the user confirms the exact external change.",
+        describeAllowedComposioActions(integration.allowedTools),
+      ].join("\n\n"),
+      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. Use the action notes in the tool description; do not rely on Composio defaults for dates, times, durations, recipients, or write behavior.",
+          },
+          confirmed: {
+            type: "boolean",
+            description:
+              "Set true only after explicit user confirmation for external write actions such as create, update, delete, send, patch, move, insert, clear, remove, import, or quick add.",
+          },
+        },
+        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.`,
+          );
+        }
+
+        validateComposioArguments(input.toolSlug, input.arguments);
+        validateComposioConfirmation(input.toolSlug, input.confirmed, integration);
+
+        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();
+}
+
+function describeAllowedComposioActions(actions: string[]): string {
+  const lines = ["Allowed Composio actions:"];
+
+  for (const action of actions) {
+    const guide = COMPOSIO_ACTION_GUIDES[action];
+
+    if (!guide) {
+      lines.push(`- ${action}: Pass explicit arguments from the current Composio action schema. Do not invent fields or rely on hidden defaults.`);
+      continue;
+    }
+
+    lines.push(`- ${action}: ${guide.summary}`);
+
+    for (const note of guide.argumentNotes) {
+      lines.push(`  - ${note}`);
+    }
+
+    for (const warning of guide.dangerousDefaults ?? []) {
+      lines.push(`  - Dangerous default: ${warning}`);
+    }
+
+    for (const example of guide.examples ?? []) {
+      lines.push(`  - Example arguments: ${JSON.stringify(example)}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function validateComposioArguments(toolSlug: string, args: Record<string, unknown>): void {
+  if (toolSlug !== "GOOGLECALENDAR_CREATE_EVENT") {
+    return;
+  }
+
+  const start = args.start_datetime;
+
+  if (typeof start !== "string" || !isUtcDateTime(start)) {
+    throw new AgentKitError(
+      "composio_argument_invalid",
+      "GOOGLECALENDAR_CREATE_EVENT requires start_datetime as an explicit UTC RFC3339 timestamp ending in Z or +00:00. Convert user-local times using the runtime time zone before calling Composio.",
+    );
+  }
+
+  const minutes = args.event_duration_minutes;
+  const hours = args.event_duration_hour;
+
+  if (!isPositiveNumber(minutes) && !isPositiveNumber(hours)) {
+    throw new AgentKitError(
+      "composio_argument_required",
+      "GOOGLECALENDAR_CREATE_EVENT requires explicit event_duration_minutes or event_duration_hour. Composio defaults event_duration_minutes to 30, so AgentKit blocks implicit duration.",
+    );
+  }
+}
+
+function validateComposioConfirmation(
+  toolSlug: string,
+  confirmed: boolean | undefined,
+  integration: ComposioManagedIntegration,
+): void {
+  if (integration.confirmExternalWrites === false || !isComposioWriteAction(toolSlug)) {
+    return;
+  }
+
+  if (confirmed !== true) {
+    throw new AgentKitError(
+      "composio_confirmation_required",
+      `Composio action ${toolSlug} changes an external system. Ask the user to confirm the exact action and call again with confirmed: true.`,
+    );
+  }
+}
+
+function isComposioWriteAction(toolSlug: string): boolean {
+  return /_(?:BATCH|CLEAR|CREATE|DELETE|DUPLICATE|IMPORT|INSERT|MOVE|PATCH|QUICK_ADD|REMOVE|REVOKE|SEND|UPDATE)(?:_|$)/.test(
+    toolSlug,
+  );
+}
+
+function isUtcDateTime(value: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|\+00:00)$/.test(value);
+}
+
+function isPositiveNumber(value: unknown): boolean {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+const COMPOSIO_ACTION_GUIDES: Record<string, ComposioActionGuide> = {
+  GOOGLECALENDAR_EVENTS_LIST: {
+    summary: "List events from a calendar before answering schedule/availability questions.",
+    argumentNotes: [
+      "calendarId is required by Composio; use primary unless the user selected a different calendar.",
+      "Use explicit timeMin and timeMax RFC3339 bounds for the requested window.",
+      "Pass timeZone when the user or business timezone matters.",
+    ],
+    examples: [
+      {
+        calendarId: "primary",
+        timeMin: "2026-06-03T00:00:00-03:00",
+        timeMax: "2026-06-04T00:00:00-03:00",
+        singleEvents: true,
+        orderBy: "startTime",
+        timeZone: "America/Sao_Paulo",
+      },
+    ],
+  },
+  GOOGLECALENDAR_CREATE_EVENT: {
+    summary: "Create an event only after confirming the exact title, date, start time, duration, timezone, and attendees/location when relevant.",
+    argumentNotes: [
+      "start_datetime is required and must be UTC RFC3339, for example 2026-06-03T15:00:00Z for 12:00 in America/Sao_Paulo.",
+      "calendar_id defaults to primary; pass it explicitly when known.",
+      "event_duration_minutes or event_duration_hour must be explicit.",
+      "Set timezone to the user/business IANA timezone when known.",
+    ],
+    dangerousDefaults: [
+      "event_duration_minutes defaults to 30 if omitted.",
+      "calendar_id defaults to primary if omitted.",
+    ],
+    examples: [
+      {
+        calendar_id: "primary",
+        summary: "Client call",
+        start_datetime: "2026-06-03T15:00:00Z",
+        event_duration_minutes: 60,
+        timezone: "America/Sao_Paulo",
+      },
+    ],
+  },
+  GOOGLECALENDAR_UPDATE_EVENT: {
+    summary: "Update an existing event only after identifying the event and confirming the exact change.",
+    argumentNotes: [
+      "Read or find the event first so event_id/calendar_id are correct.",
+      "When changing time, use explicit UTC RFC3339 values and preserve duration unless the user changed it.",
+      "Do not infer cancellation/deletion from vague wording.",
+    ],
+  },
+  GMAIL_FETCH_EMAILS: {
+    summary: "Fetch emails for read/search requests.",
+    argumentNotes: ["Use narrow query/window arguments when available; do not fetch broad mailbox history unnecessarily."],
+  },
+  GMAIL_SEND_EMAIL: {
+    summary: "Send email only after confirming recipients, subject, body, and attachments/links.",
+    argumentNotes: ["Pass recipient fields explicitly and avoid using draft-like placeholders in production sends."],
+  },
+};
+
+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);
+}