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

package/src/index.ts

@@ -2,10 +2,13 @@ export type AgentRuntime = "local" | "edge";
 export type AgentProviderName = "test" | "openai" | "anthropic" | "openrouter" | "custom";
 export type AccessMode = "private" | "token" | "public";
 export type ToolVisibility = "user" | "internal";
-export type ChannelType = "website" | "telegram" | "whatsapp";
-export type ChannelProvider = "agentkit" | "telegram" | "zapster" | "meta";
+export type ChannelType = "website" | "telegram" | "whatsapp" | "discord" | "slack";
+export type ChannelProvider = "agentkit" | "telegram" | "zapster" | "meta" | "discord" | "slack";
 export type WhatsappChannelProvider = "zapster" | "meta";
+export type DiscordChannelMode = "interactions" | "bot";
 export type TelegramAllowedUpdate = "message";
+export type ChannelAudioMode = "off" | "reject" | "transcribe";
+export type TranscriptionProviderName = "test" | "openai" | "groq";
 
 export type AgentProvider = {
   name: AgentProviderName;
@@ -17,6 +20,67 @@ export type ChannelLimits = {
   usdPerDay?: number;
 };
 
+export type ChannelBufferMode = "off" | "debounce";
+
+export type ChannelBufferInput = {
+  mode?: ChannelBufferMode;
+  quietWindowMs?: number;
+  maxWaitMs?: number;
+  maxMessages?: number;
+  maxChars?: number;
+};
+
+export type ChannelBufferConfig =
+  | {
+      mode: "off";
+    }
+  | {
+      mode: "debounce";
+      quietWindowMs: number;
+      maxWaitMs: number;
+      maxMessages: number;
+      maxChars: number;
+    };
+
+export type ChannelAudioInput = {
+  mode?: ChannelAudioMode;
+  fallbackMessage?: string;
+  maxDurationSeconds?: number;
+  maxBytes?: number;
+};
+
+export type ChannelAudioConfig =
+  | {
+      mode: "off";
+    }
+  | {
+      mode: "reject";
+      fallbackMessage: string;
+      maxDurationSeconds?: number;
+      maxBytes?: number;
+    }
+  | {
+      mode: "transcribe";
+      fallbackMessage: string;
+      maxDurationSeconds?: number;
+      maxBytes?: number;
+    };
+
+export type AgentTranscriptionLimits = {
+  maxDurationSeconds?: number;
+  maxBytes?: number;
+};
+
+export type AgentTranscriptionConfig = {
+  provider: TranscriptionProviderName;
+  model: string;
+  secret?: string;
+  language?: string;
+  prompt?: string;
+  limits?: AgentTranscriptionLimits;
+  rawAudioTtlSeconds?: number;
+};
+
 export type WebsiteChannelAccess = {
   mode: "token";
 };
@@ -26,6 +90,8 @@ export type WebsiteChannelInput = {
   access?: WebsiteChannelAccess;
   secrets?: string[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
+  audio?: ChannelAudioInput;
 };
 
 export type WebsiteChannelConfig = {
@@ -35,6 +101,8 @@ export type WebsiteChannelConfig = {
   access: WebsiteChannelAccess;
   secrets: string[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
+  audio?: ChannelAudioConfig;
 };
 
 export type TelegramChannelInput = {
@@ -42,6 +110,8 @@ export type TelegramChannelInput = {
   secrets?: string[];
   allowedUpdates?: TelegramAllowedUpdate[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
+  audio?: ChannelAudioInput;
 };
 
 export type TelegramChannelConfig = {
@@ -51,6 +121,8 @@ export type TelegramChannelConfig = {
   secrets: string[];
   allowedUpdates: TelegramAllowedUpdate[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
+  audio?: ChannelAudioConfig;
 };
 
 export type WhatsappChannelInput = {
@@ -58,6 +130,8 @@ export type WhatsappChannelInput = {
   provider: WhatsappChannelProvider;
   secrets?: string[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
+  audio?: ChannelAudioInput;
 };
 
 export type WhatsappChannelConfig = {
@@ -66,9 +140,78 @@ export type WhatsappChannelConfig = {
   name: string;
   secrets: string[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
+  audio?: ChannelAudioConfig;
 };
 
-export type AgentChannel = WebsiteChannelConfig | TelegramChannelConfig | WhatsappChannelConfig;
+export type DiscordChannelInput = {
+  name: string;
+  mode?: DiscordChannelMode;
+  secrets?: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
+};
+
+export type DiscordChannelConfig = {
+  type: "discord";
+  provider: "discord";
+  name: string;
+  mode: DiscordChannelMode;
+  secrets: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
+  audio?: never;
+};
+
+export type SlackChannelInput = {
+  name: string;
+  secrets?: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
+};
+
+export type SlackChannelConfig = {
+  type: "slack";
+  provider: "slack";
+  name: string;
+  secrets: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
+  audio?: never;
+};
+
+export type AgentChannel =
+  | WebsiteChannelConfig
+  | TelegramChannelConfig
+  | WhatsappChannelConfig
+  | DiscordChannelConfig
+  | SlackChannelConfig;
+
+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 =
   | {
@@ -77,6 +220,7 @@ export type AgentDatabaseConfig =
   | {
       driver: "turso";
       schema?: string;
+      migrations?: string;
     };
 
 export type AgentFilesConfig =
@@ -90,6 +234,37 @@ export type AgentFilesConfig =
       maxUploadBytes?: number;
     };
 
+export type AgentKnowledgeSource =
+  | string
+  | {
+      path: string;
+      title?: string;
+    }
+  | {
+      url: string;
+      title?: string;
+    };
+
+export type AgentKnowledgeEmbeddingProvider = "none" | "test" | "openai";
+
+export type AgentKnowledgeEmbeddingConfig = {
+  provider?: AgentKnowledgeEmbeddingProvider;
+  model?: string;
+  dimensions?: number;
+  secret?: string;
+};
+
+export type AgentKnowledgeRetrievalConfig = {
+  topK?: number;
+  hybrid?: boolean;
+};
+
+export type AgentKnowledgeConfig = {
+  sources?: AgentKnowledgeSource[];
+  embedding?: AgentKnowledgeEmbeddingConfig;
+  retrieval?: AgentKnowledgeRetrievalConfig;
+};
+
 export type JsonSchema = {
   type: string | string[];
   properties?: Record<string, JsonSchema>;
@@ -119,17 +294,61 @@ export type DatabaseRunner = {
   batch(statements: DatabaseStatement[]): Promise<DatabaseResult[]>;
 };
 
+export type ToolRenderField = {
+  label: string;
+  value: string;
+};
+
+export type ToolRenderAction = {
+  label: string;
+  href?: string;
+};
+
+export type ToolRenderBlock =
+  | {
+      type: "text";
+      text: string;
+    }
+  | {
+      type: "card";
+      title: string;
+      subtitle?: string;
+      fields?: ToolRenderField[];
+      actions?: ToolRenderAction[];
+    };
+
+export type ToolRenderResult = {
+  text: string;
+  blocks?: ToolRenderBlock[];
+};
+
+export type ToolRenderContext<Input = unknown> = {
+  input: Input;
+  runtime: ToolRuntimeContext;
+  clock: ToolClockContext;
+};
+
 export type ToolRuntimeContext = {
   environment: "local" | "hosted" | "eval" | "test";
-  invocation: "chat" | "tool" | "dev" | "channel" | "eval";
+  invocation: "chat" | "tool" | "dev" | "channel" | "eval" | "sync";
   target: "bun" | "cloudflare";
   database: "sqlite" | "turso" | "none";
 };
 
+export type ToolClockContext = {
+  now: Date;
+  isoTimestamp: string;
+  timeZone: string;
+  localDate: string;
+  localWeekday: string;
+  localDateTime: string;
+};
+
 export type ToolContext = {
   secrets: Record<string, string>;
   signal: AbortSignal;
   runtime: ToolRuntimeContext;
+  clock: ToolClockContext;
   database: DatabaseRunner;
   db: DatabaseRunner;
   storage: {
@@ -137,6 +356,13 @@ export type ToolContext = {
   };
 };
 
+export type SyncContext = {
+  env: Record<string, string | undefined>;
+  database: DatabaseRunner;
+  db: DatabaseRunner;
+  runtime: ToolRuntimeContext;
+};
+
 export type AgentTool<Input = unknown, Output = unknown> = {
   name: string;
   description: string;
@@ -147,16 +373,21 @@ export type AgentTool<Input = unknown, Output = unknown> = {
   permissions?: string[];
   timeoutMs?: number;
   execute(input: Input, ctx: ToolContext): Promise<Output> | Output;
+  render?(output: Output, ctx: ToolRenderContext<Input>): string | ToolRenderResult;
 };
 
 export type AgentConfig = {
   name: string;
   runtime: AgentRuntime;
   provider: AgentProvider;
+  timeZone?: string;
   instructions: string;
   secrets: string[];
   tools?: AgentTool[];
+  integrations?: AgentIntegration[];
   channels?: AgentChannel[];
+  transcription?: AgentTranscriptionConfig;
+  knowledge?: AgentKnowledgeConfig;
   access: {
     mode: AccessMode;
   };
@@ -176,6 +407,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",
@@ -184,6 +434,8 @@ export function websiteChannel(input: WebsiteChannelInput): WebsiteChannelConfig
     access: input.access ?? { mode: "token" },
     secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"], "website channel"),
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "website channel") } : {}),
+    ...(input.audio ? { audio: normalizeChannelAudio(input.audio, "website channel") } : {}),
   };
 }
 
@@ -198,6 +450,8 @@ export function telegramChannel(input: TelegramChannelInput): TelegramChannelCon
     ),
     allowedUpdates: input.allowedUpdates ?? ["message"],
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "telegram channel") } : {}),
+    ...(input.audio ? { audio: normalizeChannelAudio(input.audio, "telegram channel") } : {}),
   };
 }
 
@@ -211,12 +465,43 @@ export function whatsappChannel(input: WhatsappChannelInput): WhatsappChannelCon
       `${input.provider} whatsapp channel`,
     ),
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, `${input.provider} whatsapp channel`) } : {}),
+    ...(input.audio ? { audio: normalizeChannelAudio(input.audio, `${input.provider} whatsapp channel`) } : {}),
+  };
+}
+
+export function discordChannel(input: DiscordChannelInput): DiscordChannelConfig {
+  const mode = input.mode ?? "interactions";
+
+  return {
+    type: "discord",
+    provider: "discord",
+    name: input.name,
+    mode,
+    secrets: normalizeChannelSecrets(input.secrets ?? defaultDiscordChannelSecrets(mode), "discord channel"),
+    ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "discord channel") } : {}),
+  };
+}
+
+export function slackChannel(input: SlackChannelInput): SlackChannelConfig {
+  return {
+    type: "slack",
+    provider: "slack",
+    name: input.name,
+    secrets: normalizeChannelSecrets(input.secrets ?? ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"], "slack channel"),
+    ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "slack channel") } : {}),
   };
 }
 
+function defaultDiscordChannelSecrets(mode: DiscordChannelMode): string[] {
+  return mode === "bot" ? ["DISCORD_BOT_TOKEN"] : ["DISCORD_PUBLIC_KEY"];
+}
+
 function defaultWhatsappChannelSecrets(provider: WhatsappChannelProvider): string[] {
   if (provider === "zapster") {
-    return ["ZAPSTER_API_KEY", "ZAPSTER_WEBHOOK_SECRET"];
+    return ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"];
   }
 
   return ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"];
@@ -236,32 +521,219 @@ 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" };
+  }
+
+  if (input.mode !== undefined && input.mode !== "debounce") {
+    throw new Error(`${context} buffer.mode must be "off" or "debounce".`);
+  }
+
+  const buffer: ChannelBufferConfig = {
+    mode: "debounce",
+    quietWindowMs: input.quietWindowMs ?? 2500,
+    maxWaitMs: input.maxWaitMs ?? 12000,
+    maxMessages: input.maxMessages ?? 20,
+    maxChars: input.maxChars ?? 8000,
+  };
+
+  validatePositiveInteger(buffer.quietWindowMs, `${context} buffer.quietWindowMs`);
+  validatePositiveInteger(buffer.maxWaitMs, `${context} buffer.maxWaitMs`);
+  validatePositiveInteger(buffer.maxMessages, `${context} buffer.maxMessages`);
+  validatePositiveInteger(buffer.maxChars, `${context} buffer.maxChars`);
+
+  if (buffer.maxWaitMs < buffer.quietWindowMs) {
+    throw new Error(`${context} buffer.maxWaitMs must be greater than or equal to buffer.quietWindowMs.`);
+  }
+
+  return buffer;
+}
+
+function normalizeChannelAudio(input: ChannelAudioInput, context: string): ChannelAudioConfig {
+  const mode = input.mode ?? "transcribe";
+
+  if (mode !== "off" && mode !== "reject" && mode !== "transcribe") {
+    throw new Error(`${context} audio.mode must be "off", "reject", or "transcribe".`);
+  }
+
+  if (mode === "off") {
+    return { mode: "off" };
+  }
+
+  if (input.maxDurationSeconds !== undefined) {
+    validatePositiveInteger(input.maxDurationSeconds, `${context} audio.maxDurationSeconds`);
+  }
+
+  if (input.maxBytes !== undefined) {
+    validatePositiveInteger(input.maxBytes, `${context} audio.maxBytes`);
+  }
+
+  return {
+    mode,
+    fallbackMessage: input.fallbackMessage ?? "I received an audio message, but I could not transcribe it. Please send the message as text.",
+    ...(input.maxDurationSeconds !== undefined ? { maxDurationSeconds: input.maxDurationSeconds } : {}),
+    ...(input.maxBytes !== undefined ? { maxBytes: input.maxBytes } : {}),
+  };
+}
+
+function validatePositiveInteger(value: number, field: string): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${field} must be a positive integer.`);
+  }
+}
+
 export { loadAgentCapsule, findAgentCapsuleRoot } from "./runtime/config";
 export { runAgentMessage, runAgentMessageFromCwd } from "./runtime/chat";
 export { listConversationsFromCwd, getConversationFromCwd } from "./runtime/conversations";
-export { runEvalsFromCwd } from "./runtime/evals";
+export { defineEval, runEvalsFromCwd } from "./runtime/evals";
+export type {
+  EvalCase,
+  EvalExpect,
+  EvalResponseExpectation,
+  EvalRunSummary,
+  EvalResult,
+  EvalToolsContainerExpectation,
+  EvalToolsExpectation,
+  EvalTurn,
+  ToolExpectation,
+} from "./runtime/evals";
+export { getConversationTraceFromCwd } from "./runtime/traces";
 export { runToolFromCwd } from "./runtime/tool-runner";
 export { startAgentDevServer } from "./runtime/dev-server";
 export { inspectAgentCapsule } from "./runtime/inspect";
 export { buildAgentCapsule } from "./runtime/build";
-export { deployBuildToAgentKitCloud, startAgentKitCloudServer } from "./runtime/deploy";
+export { deployBuildToAgentKitCloud } from "./runtime/deploy";
 export { AgentKitError } from "./runtime/errors";
 export type {
   ChannelAdapter,
   ChannelAdapterId,
+  ChannelAudioAttachment,
   ChannelDeliveryDirection,
   ChannelDeliveryState,
   ChannelEventKind,
   ChannelExternalIdentity,
+  ChannelMediaDownloadInput,
+  ChannelMediaDownloadResult,
   ChannelMessageContentType,
   ChannelMessageRole,
+  ChannelReplyTarget,
   ChannelSendInput,
   ChannelSendResult,
   ChannelStatusInput,
   ChannelStatusResult,
+  ChannelWebhookResponse,
   NormalizedChannelEvent,
   NormalizedChannelMessage,
   RawWebhookEvent,
   WebhookVerificationInput,
   WebhookVerificationResult,
 } from "./runtime/channels";
+export type {
+  TranscriptionAdapter,
+  TranscriptionInput,
+  TranscriptionResult,
+} from "./runtime/transcription";