@andreprado/agentkit 0.1.0 → 0.2.0

package/src/runtime/deploy-readiness.ts

@@ -1,135 +0,0 @@
-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;
-  environment: boolean;
-};
-
-export type DeployReadinessContext = {
-  root: string;
-  projectName: string;
-  projectId: string;
-  target: "cloudflare";
-  runtime: "edge" | "local";
-  provider: {
-    name: string;
-    model: string;
-  };
-  accessMode: "private" | "token" | "public";
-  requiredSecrets: string[];
-  userManagedSecrets: string[];
-  agentKitManagedSecrets: string[];
-  localSecrets: Record<string, DeployReadinessSecretSource>;
-  knowledge: {
-    enabled: boolean;
-    sourceCount: number;
-    embeddingProvider: string;
-    databaseDriver: "none" | "turso";
-  };
-  integrations: {
-    managedComposio: {
-      enabled: boolean;
-      toolkits: string[];
-      toolCount: number;
-      userId: string | null;
-    };
-  };
-};
-
-export async function loadDeployReadinessContext(
-  cwd = process.cwd(),
-  env: Record<string, string | undefined> = process.env,
-): 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> = {};
-
-  for (const name of requiredSecrets) {
-    const source = {
-      dotenv: dotenvNames.has(name),
-      environment: Boolean(env[name]),
-    };
-
-    if (source.dotenv || source.environment) {
-      localSecrets[name] = source;
-    }
-  }
-
-  const agentKitManagedSecrets = requiredSecrets.filter((name) =>
-    isAgentKitManagedDeploySecret(name, {
-      accessMode: capsule.config.access.mode,
-      databaseDriver: manifest.storage.database.driver,
-      managedComposioEnabled: Boolean(managedComposio),
-    }),
-  );
-  const managed = new Set(agentKitManagedSecrets);
-
-  return {
-    root: capsule.root,
-    projectName: capsule.config.name,
-    projectId: stableCloudProjectId(capsule.config.name),
-    target: "cloudflare",
-    runtime: capsule.config.runtime,
-    provider: {
-      name: capsule.config.provider.name,
-      model: capsule.config.provider.model,
-    },
-    accessMode: capsule.config.access.mode,
-    requiredSecrets,
-    userManagedSecrets: requiredSecrets.filter((name) => !managed.has(name)),
-    agentKitManagedSecrets,
-    localSecrets,
-    knowledge: {
-      enabled: manifest.knowledge.enabled,
-      sourceCount: manifest.knowledge.sources.length,
-      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,
-      },
-    },
-  };
-}
-
-export function stableCloudProjectId(name: string, accountId?: string | null): string {
-  return `proj_${createHash("sha256").update(`${accountId ? `account:${accountId}` : "anonymous"}:${name}`).digest("hex").slice(0, 16)}`;
-}
-
-function isAgentKitManagedDeploySecret(
-  name: string,
-  context: {
-    accessMode: DeployReadinessContext["accessMode"];
-    databaseDriver: "none" | "turso";
-    managedComposioEnabled: boolean;
-  },
-): boolean {
-  if (context.databaseDriver === "turso" && (name === "TURSO_DATABASE_URL" || name === "TURSO_AUTH_TOKEN")) {
-    return true;
-  }
-
-  if (name === "AGENTKIT_PRIVATE_TOKEN") {
-    return true;
-  }
-
-  if (context.managedComposioEnabled && name === MANAGED_COMPOSIO_API_KEY_SECRET) {
-    return true;
-  }
-
-  return false;
-}

package/src/runtime/deploy.ts

@@ -1 +0,0 @@
-export * from "../cloud";

package/src/runtime/integrations/composio.ts

@@ -1,425 +0,0 @@
-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()}:${isComposioWriteAction(toolName) ? "write" : "read"}`,
-      ),
-      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);
-}