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

package/src/runtime/inspect.ts

@@ -4,9 +4,16 @@ 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";
 
@@ -20,7 +27,21 @@ export type AgentInspectState = {
   };
   prompt: string;
   tools: string[];
+  integrations: AgentInspectIntegration[];
   channels: AgentInspectChannel[];
+  transcription: {
+    enabled: boolean;
+    provider: string | null;
+    model: string | null;
+    secret: string | null;
+    language: string | null;
+    prompt: string | null;
+    limits: {
+      maxDurationSeconds: number | null;
+      maxBytes: number | null;
+    };
+    rawAudioTtlSeconds: number | null;
+  };
   knowledge: {
     enabled: boolean;
     sources: string[];
@@ -57,6 +78,8 @@ export type AgentInspectState = {
   secrets: Record<string, SecretState>;
   managedSecrets: string[];
   userSecrets: string[];
+  skills: AgentInspectSkills;
+  warnings: AgentInspectWarning[];
 };
 
 export type AgentInspectDatabase = {
@@ -80,6 +103,30 @@ export type AgentInspectChannel = {
   provider: AgentChannel["provider"];
   secrets: string[];
   buffer?: AgentChannel["buffer"];
+  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(
@@ -87,17 +134,20 @@ export async function inspectAgentCapsule(
   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);
     }
@@ -113,8 +163,15 @@ export function buildInspectState(
     declaredSecrets.add(knowledge.embedding.secret);
   }
 
+  if (transcription.secret) {
+    declaredSecrets.add(transcription.secret);
+  }
+
   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) {
@@ -123,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,
@@ -135,14 +195,36 @@ 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,
+    })),
     channels: (capsule.config.channels ?? []).map((channel) => ({
       name: channel.name,
       type: channel.type,
       provider: channel.provider,
       secrets: [...channel.secrets],
       ...(channel.buffer ? { buffer: channel.buffer } : {}),
+      ...(channel.audio ? { audio: channel.audio } : {}),
     })),
+    transcription: {
+      enabled: transcription.enabled,
+      provider: transcription.enabled ? transcription.provider : null,
+      model: transcription.enabled ? transcription.model : null,
+      secret: transcription.secret,
+      language: transcription.language,
+      prompt: transcription.prompt,
+      limits: {
+        maxDurationSeconds: transcription.limits.maxDurationSeconds ?? null,
+        maxBytes: transcription.limits.maxBytes ?? null,
+      },
+      rawAudioTtlSeconds: transcription.rawAudioTtlSeconds,
+    },
     knowledge: {
       enabled: knowledge.enabled,
       sources: knowledge.sources.map((source) => source.value),
@@ -174,6 +256,8 @@ export function buildInspectState(
     secrets,
     managedSecrets,
     userSecrets,
+    skills,
+    warnings,
   };
 }
 
@@ -203,6 +287,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>();
 
@@ -211,5 +345,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,257 @@
+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>;
+};
+
+type ManagedComposioToolOutput = {
+  successful: boolean;
+  data: unknown;
+  error: unknown;
+  logId: string | null;
+  toolkit: string;
+  toolSlug: string;
+  userId: string;
+};
+
+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.",
+      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.",
+          },
+        },
+        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.`,
+          );
+        }
+
+        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();
+}
+
+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);
+}

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