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

package/src/runtime/inspect.ts

@@ -4,9 +4,15 @@ import type { AgentChannel, AgentProvider, AgentRuntime, AccessMode } from "../i
 import type { LoadedAgentCapsule } from "./config";
 import { loadAgentCapsule } from "./config";
 import { loadCapsuleEnv } from "./env";
+import {
+  createManagedComposioTools,
+  managedComposioRequiredSecrets,
+  resolveManagedComposioIntegrations,
+} from "./integrations/composio";
 import { resolveKnowledgeConfig } from "./knowledge/config";
 import { KNOWLEDGE_SEARCH_TOOL_NAME } from "./knowledge/tool";
 import { resolveRuntimeTimeZone } from "./prompt-context";
+import { checkDefaultSkillStatus, type DefaultSkillStatus } from "./skills";
 import { resolveTranscriptionConfig } from "./transcription";
 
 export type SecretState = "set" | "missing";
@@ -21,6 +27,7 @@ export type AgentInspectState = {
   };
   prompt: string;
   tools: string[];
+  integrations: AgentInspectIntegration[];
   channels: AgentInspectChannel[];
   transcription: {
     enabled: boolean;
@@ -71,6 +78,8 @@ export type AgentInspectState = {
   secrets: Record<string, SecretState>;
   managedSecrets: string[];
   userSecrets: string[];
+  skills: AgentInspectSkills;
+  warnings: AgentInspectWarning[];
 };
 
 export type AgentInspectDatabase = {
@@ -97,23 +106,48 @@ export type AgentInspectChannel = {
   audio?: AgentChannel["audio"];
 };
 
+export type AgentInspectSkills = {
+  status: "current" | "missing" | "outdated" | "not_checked";
+  checked: number;
+  missing: string[];
+  outdated: string[];
+  syncCommand: string | null;
+};
+
+export type AgentInspectWarning = {
+  code: string;
+  message: string;
+  command?: string;
+};
+
+export type AgentInspectIntegration = {
+  name: string;
+  provider: "composio";
+  mode: "managed";
+  toolkits: string[];
+  tools: string[];
+  userId: string;
+};
+
 export async function inspectAgentCapsule(
   cwd = process.cwd(),
   env: Record<string, string | undefined> = process.env,
 ): Promise<AgentInspectState> {
   const capsule = await loadAgentCapsule(cwd);
-  return buildInspectState(capsule, await loadCapsuleEnv(capsule.root, env));
+  return buildInspectState(capsule, await loadCapsuleEnv(capsule.root, env), await checkDefaultSkillStatus(capsule.root));
 }
 
 export function buildInspectState(
   capsule: LoadedAgentCapsule,
   env: Record<string, string | undefined> = process.env,
+  skillStatus: DefaultSkillStatus | null = null,
 ): AgentInspectState {
   const declaredSecrets = new Set(capsule.config.secrets);
   const knowledge = resolveKnowledgeConfig(capsule.config);
+  const integrationTools = createManagedComposioTools(capsule.config);
   const transcription = resolveTranscriptionConfig(capsule.config.transcription);
 
-  for (const tool of capsule.config.tools ?? []) {
+  for (const tool of [...integrationTools, ...(capsule.config.tools ?? [])]) {
     for (const secret of tool.secrets ?? []) {
       declaredSecrets.add(secret);
     }
@@ -134,7 +168,10 @@ export function buildInspectState(
   }
 
   const managedSecrets = managedCloudSecrets(capsule);
-  const userSecrets = Array.from(declaredSecrets).sort();
+  const managedSecretSet = new Set(managedSecrets);
+  const userSecrets = Array.from(declaredSecrets)
+    .filter((secret) => !managedSecretSet.has(secret))
+    .sort();
   const secrets: Record<string, SecretState> = {};
 
   for (const secret of userSecrets) {
@@ -143,6 +180,9 @@ export function buildInspectState(
 
   const database = inspectDatabase(capsule);
 
+  const skills = inspectSkills(skillStatus);
+  const warnings = inspectWarnings(capsule, transcription, skills);
+
   return {
     agent: capsule.config.name,
     runtime: capsule.config.runtime,
@@ -155,7 +195,16 @@ export function buildInspectState(
       }),
     },
     prompt: toCapsulePath(capsule.root, capsule.instructionsPath),
-    tools: (capsule.config.tools ?? []).map((tool) => tool.name),
+    tools: [...integrationTools, ...(capsule.config.tools ?? [])].map((tool) => tool.name),
+    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 ?? []).map((channel) => ({
       name: channel.name,
       type: channel.type,
@@ -208,6 +257,8 @@ export function buildInspectState(
     secrets,
     managedSecrets,
     userSecrets,
+    skills,
+    warnings,
   };
 }
 
@@ -237,6 +288,56 @@ function inspectDatabase(capsule: LoadedAgentCapsule): AgentInspectDatabase {
   };
 }
 
+function inspectSkills(status: DefaultSkillStatus | null): AgentInspectSkills {
+  if (!status) {
+    return {
+      status: "not_checked",
+      checked: 0,
+      missing: [],
+      outdated: [],
+      syncCommand: null,
+    };
+  }
+
+  return {
+    status: status.status,
+    checked: status.checked,
+    missing: status.missing,
+    outdated: status.outdated,
+    syncCommand: status.status === "current" ? null : "npm run agentkit -- skills sync",
+  };
+}
+
+function inspectWarnings(
+  capsule: LoadedAgentCapsule,
+  transcription: ReturnType<typeof resolveTranscriptionConfig>,
+  skills: AgentInspectSkills,
+): AgentInspectWarning[] {
+  const warnings: AgentInspectWarning[] = [];
+
+  if (skills.status === "missing" || skills.status === "outdated") {
+    warnings.push({
+      code: "local_skills_outdated",
+      message: "Local AgentKit skills are older than or missing from the installed package docs.",
+      command: "npm run agentkit -- skills sync",
+    });
+  }
+
+  if (
+    transcription.enabled &&
+    transcription.provider === "openai" &&
+    (capsule.config.channels ?? []).some((channel) => channel.type === "telegram" && channel.audio?.mode === "transcribe")
+  ) {
+    warnings.push({
+      code: "telegram_audio_openai_format",
+      message: "Telegram voice notes arrive as OGG/Opus; use Groq for the default Telegram voice-note transcription path.",
+      command: "Set transcription.provider to \"groq\" and secret to \"GROQ_API_KEY\".",
+    });
+  }
+
+  return warnings;
+}
+
 function managedCloudSecrets(capsule: LoadedAgentCapsule): string[] {
   const secrets = new Set<string>();
 
@@ -245,5 +346,9 @@ function managedCloudSecrets(capsule: LoadedAgentCapsule): string[] {
     secrets.add("TURSO_DATABASE_URL");
   }
 
+  for (const secret of managedComposioRequiredSecrets(capsule.config)) {
+    secrets.add(secret);
+  }
+
   return Array.from(secrets).sort();
 }

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);
+}