@andreprado/agentkit 0.1.0-alpha.10

package/src/runtime/config.ts

@@ -0,0 +1,684 @@
+import { access, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import type {
+  AgentConfig,
+  AgentProviderName,
+  AgentRuntime,
+  AccessMode,
+  AgentTool,
+  ToolVisibility,
+  AgentChannel,
+  ChannelProvider,
+  ChannelType,
+  TelegramAllowedUpdate,
+  AgentKnowledgeEmbeddingProvider,
+  ChannelBufferMode,
+} from "../index";
+import { AgentKitError } from "./errors";
+
+const CONFIG_FILE = "agentkit.config.ts";
+const AGENT_RUNTIMES = new Set<AgentRuntime>(["local", "edge"]);
+const PROVIDERS = new Set<AgentProviderName>(["test", "openai", "anthropic", "openrouter", "custom"]);
+const ACCESS_MODES = new Set<AccessMode>(["private", "token", "public"]);
+const TOOL_VISIBILITIES = new Set<ToolVisibility>(["user", "internal"]);
+const CHANNEL_TYPES = new Set<ChannelType>(["website", "telegram", "whatsapp"]);
+const CHANNEL_PROVIDERS = new Set<ChannelProvider>(["agentkit", "telegram", "zapster", "meta"]);
+const CHANNEL_BUFFER_MODES = new Set<ChannelBufferMode>(["off", "debounce"]);
+const TELEGRAM_ALLOWED_UPDATES = new Set<TelegramAllowedUpdate>(["message"]);
+const KNOWLEDGE_EMBEDDING_PROVIDERS = new Set<AgentKnowledgeEmbeddingProvider>(["none", "test", "openai"]);
+const CHANNEL_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const SECRET_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+
+export type LoadedAgentCapsule = {
+  root: string;
+  configPath: string;
+  config: AgentConfig;
+  instructionsPath: string;
+  instructions: string;
+  storagePath?: string;
+};
+
+export async function findAgentCapsuleRoot(cwd: string): Promise<string> {
+  let current = resolve(cwd);
+
+  while (true) {
+    const configPath = join(current, CONFIG_FILE);
+
+    if (await fileExists(configPath)) {
+      return current;
+    }
+
+    const parent = dirname(current);
+
+    if (parent === current) {
+      throw new AgentKitError(
+        "missing_config",
+        `No ${CONFIG_FILE} found from ${resolve(cwd)} or any parent directory. Run this command from an Agent Capsule root.`,
+      );
+    }
+
+    current = parent;
+  }
+}
+
+export async function loadAgentCapsule(cwd = process.cwd()): Promise<LoadedAgentCapsule> {
+  const root = await findAgentCapsuleRoot(cwd);
+  const configPath = join(root, CONFIG_FILE);
+  const config = await loadConfigModule(configPath);
+  validateAgentConfig(config);
+
+  const instructionsPath = resolvePath(root, config.instructions);
+
+  let instructions: string;
+
+  try {
+    instructions = await readFile(instructionsPath, "utf8");
+  } catch (error) {
+    throw new AgentKitError(
+      "missing_prompt",
+      `Prompt file not found at ${relative(root, instructionsPath) || config.instructions}. Check the instructions path in ${CONFIG_FILE}.`,
+      { cause: error },
+    );
+  }
+
+  return {
+    root,
+    configPath,
+    config,
+    instructionsPath,
+    instructions,
+    storagePath: resolveLocalStoragePath(root, config),
+  };
+}
+
+function resolveLocalStoragePath(root: string, config: AgentConfig): string | undefined {
+  if (config.storage.path) {
+    return resolvePath(root, config.storage.path);
+  }
+
+  if (config.storage.driver === "agentkit") {
+    return resolvePath(root, ".agentkit/agentkit.db");
+  }
+
+  return undefined;
+}
+
+async function loadConfigModule(configPath: string): Promise<unknown> {
+  const configUrl = pathToFileURL(configPath);
+  configUrl.searchParams.set("t", String(Date.now()));
+
+  try {
+    const module = (await import(configUrl.href)) as { default?: unknown };
+    return module.default;
+  } catch (error) {
+    if (isMissingAgentKitSelfImport(error)) {
+      return loadConfigModuleWithLocalSelfImport(configPath, error);
+    }
+
+    throw new AgentKitError(
+      "invalid_config",
+      `Could not load ${CONFIG_FILE}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+async function loadConfigModuleWithLocalSelfImport(configPath: string, originalError: unknown): Promise<unknown> {
+  const source = await readFile(configPath, "utf8");
+  const localAgentKitUrl = pathToFileURL(resolve(moduleDir, "../index.ts")).href;
+  const patchedSource = source.replace(
+    /from\s+["']@andreprado\/agentkit["']/g,
+    `from ${JSON.stringify(localAgentKitUrl)}`,
+  );
+
+  if (patchedSource === source) {
+    throw new AgentKitError(
+      "invalid_config",
+      `Could not load ${CONFIG_FILE}: ${originalError instanceof Error ? originalError.message : String(originalError)}`,
+      { cause: originalError },
+    );
+  }
+
+  const tempConfigPath = join(
+    dirname(configPath),
+    `.agentkit.config.loader-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.ts`,
+  );
+
+  try {
+    await writeFile(tempConfigPath, patchedSource);
+    const configUrl = pathToFileURL(tempConfigPath);
+    configUrl.searchParams.set("t", String(Date.now()));
+    const module = (await import(configUrl.href)) as { default?: unknown };
+    return module.default;
+  } catch (error) {
+    throw new AgentKitError(
+      "invalid_config",
+      `Could not load ${CONFIG_FILE}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  } finally {
+    await unlink(tempConfigPath).catch(() => undefined);
+  }
+}
+
+function isMissingAgentKitSelfImport(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("@andreprado/agentkit");
+}
+
+function validateAgentConfig(value: unknown): asserts value is AgentConfig {
+  if (!isRecord(value)) {
+    throw invalidConfig("Config must export defineAgent({...}) as the default export.");
+  }
+
+  expectString(value.name, "name");
+
+  if (!AGENT_RUNTIMES.has(value.runtime as AgentRuntime)) {
+    throw invalidConfig('runtime must be "local" or "edge".');
+  }
+
+  if (!isRecord(value.provider)) {
+    throw invalidConfig("provider must be an object with name and model.");
+  }
+
+  if (!PROVIDERS.has(value.provider.name as AgentProviderName)) {
+    throw invalidConfig(`provider.name must be one of: ${Array.from(PROVIDERS).join(", ")}.`);
+  }
+
+  expectString(value.provider.model, "provider.model");
+
+  if (value.provider.name === "test" && value.provider.model !== "fake") {
+    throw invalidConfig('provider.model must be "fake" when provider.name is "test".');
+  }
+
+  expectString(value.instructions, "instructions");
+  expectStringArray(value.secrets, "secrets");
+
+  if (value.tools !== undefined) {
+    if (!Array.isArray(value.tools)) {
+      throw invalidConfig("tools must be an array when provided.");
+    }
+
+    for (const [index, tool] of value.tools.entries()) {
+      validateTool(tool, index);
+    }
+  }
+
+  validateChannels(value.channels, value.runtime as AgentRuntime);
+  validateKnowledgeConfig(value.knowledge);
+
+  if (!isRecord(value.access) || !ACCESS_MODES.has(value.access.mode as AccessMode)) {
+    throw invalidConfig('access.mode must be "private", "token", or "public".');
+  }
+
+  if (!isRecord(value.storage)) {
+    throw invalidConfig("storage must be an object.");
+  }
+
+  if (value.storage.driver !== "sqlite" && value.storage.driver !== "agentkit") {
+    throw invalidConfig('storage.driver must be "sqlite" or "agentkit".');
+  }
+
+  if (value.storage.path !== undefined && typeof value.storage.path !== "string") {
+    throw invalidConfig("storage.path must be a string when provided.");
+  }
+
+  validateDatabaseConfig(value.storage.database);
+  validateFilesConfig(value.storage.files);
+}
+
+function validateKnowledgeConfig(value: unknown): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!isRecord(value)) {
+    throw invalidConfig("knowledge must be an object when provided.");
+  }
+
+  if (value.sources !== undefined) {
+    if (!Array.isArray(value.sources)) {
+      throw invalidConfig("knowledge.sources must be an array when provided.");
+    }
+
+    for (const [index, source] of value.sources.entries()) {
+      validateKnowledgeSource(source, index);
+    }
+  }
+
+  if (value.embedding !== undefined) {
+    validateKnowledgeEmbedding(value.embedding);
+  }
+
+  if (value.retrieval !== undefined) {
+    validateKnowledgeRetrieval(value.retrieval);
+  }
+}
+
+function validateKnowledgeSource(value: unknown, index: number): void {
+  if (typeof value === "string") {
+    expectString(value, `knowledge.sources[${index}]`);
+    validateKnowledgeSourceReference(value, `knowledge.sources[${index}]`);
+    return;
+  }
+
+  if (!isRecord(value)) {
+    throw invalidConfig(`knowledge.sources[${index}] must be a path string or an object with path or url.`);
+  }
+
+  const hasPath = "path" in value;
+  const hasUrl = "url" in value;
+
+  if (hasPath === hasUrl) {
+    throw invalidConfig(`knowledge.sources[${index}] must set exactly one of path or url.`);
+  }
+
+  if (hasPath) {
+    expectString(value.path, `knowledge.sources[${index}].path`);
+    validateKnowledgeSourceReference(value.path, `knowledge.sources[${index}].path`);
+  }
+
+  if (hasUrl) {
+    expectString(value.url, `knowledge.sources[${index}].url`);
+    validateKnowledgeUrl(value.url, `knowledge.sources[${index}].url`);
+  }
+
+  if (value.title !== undefined) {
+    expectString(value.title, `knowledge.sources[${index}].title`);
+  }
+}
+
+function validateKnowledgeSourceReference(value: string, label: string): void {
+  if (value.includes("\0")) {
+    throw invalidConfig(`${label} must not contain null bytes.`);
+  }
+
+  if (/^https?:\/\//i.test(value)) {
+    validateKnowledgeUrl(value, label);
+  }
+}
+
+function validateKnowledgeUrl(value: string, label: string): void {
+  let url: URL;
+
+  try {
+    url = new URL(value);
+  } catch {
+    throw invalidConfig(`${label} must be a valid http or https URL.`);
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw invalidConfig(`${label} must be a valid http or https URL.`);
+  }
+}
+
+function validateKnowledgeEmbedding(value: unknown): void {
+  if (!isRecord(value)) {
+    throw invalidConfig("knowledge.embedding must be an object when provided.");
+  }
+
+  if (value.provider !== undefined && !KNOWLEDGE_EMBEDDING_PROVIDERS.has(value.provider as AgentKnowledgeEmbeddingProvider)) {
+    throw invalidConfig(
+      `knowledge.embedding.provider must be one of: ${Array.from(KNOWLEDGE_EMBEDDING_PROVIDERS).join(", ")}.`,
+    );
+  }
+
+  if (value.model !== undefined) {
+    expectString(value.model, "knowledge.embedding.model");
+  }
+
+  if (value.secret !== undefined) {
+    expectString(value.secret, "knowledge.embedding.secret");
+    validateSecretNames([value.secret], "knowledge.embedding.secret");
+  }
+
+  const dimensions = value.dimensions;
+  if (dimensions !== undefined) {
+    if (typeof dimensions !== "number" || !Number.isInteger(dimensions) || dimensions <= 0 || dimensions > 65_536) {
+      throw invalidConfig("knowledge.embedding.dimensions must be a positive integer no larger than 65536.");
+    }
+  }
+}
+
+function validateKnowledgeRetrieval(value: unknown): void {
+  if (!isRecord(value)) {
+    throw invalidConfig("knowledge.retrieval must be an object when provided.");
+  }
+
+  const topK = value.topK;
+  if (topK !== undefined && (typeof topK !== "number" || !Number.isInteger(topK) || topK <= 0 || topK > 50)) {
+    throw invalidConfig("knowledge.retrieval.topK must be a positive integer no larger than 50.");
+  }
+
+  if (value.hybrid !== undefined && typeof value.hybrid !== "boolean") {
+    throw invalidConfig("knowledge.retrieval.hybrid must be a boolean when provided.");
+  }
+}
+
+function validateChannels(value: unknown, runtime: AgentRuntime): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw invalidConfig("channels must be an array when provided.");
+  }
+
+  if (value.length > 0 && runtime !== "edge") {
+    throw invalidConfig('channels require runtime: "edge".');
+  }
+
+  const names = new Set<string>();
+
+  for (const [index, channel] of value.entries()) {
+    validateChannel(channel, index);
+
+    if (names.has(channel.name)) {
+      throw invalidConfig(`channels[${index}].name must be unique within the Agent Capsule.`);
+    }
+
+    names.add(channel.name);
+  }
+}
+
+function validateChannel(value: unknown, index: number): asserts value is AgentChannel {
+  if (!isRecord(value)) {
+    throw invalidConfig(`channels[${index}] must be an object.`);
+  }
+
+  expectString(value.name, `channels[${index}].name`);
+
+  if (!CHANNEL_NAME_PATTERN.test(value.name)) {
+    throw invalidConfig(
+      `channels[${index}].name must be lowercase and contain only letters, numbers, and hyphens.`,
+    );
+  }
+
+  if (!CHANNEL_TYPES.has(value.type as ChannelType)) {
+    throw invalidConfig(`channels[${index}].type must be one of: ${Array.from(CHANNEL_TYPES).join(", ")}.`);
+  }
+
+  if (!CHANNEL_PROVIDERS.has(value.provider as ChannelProvider)) {
+    throw invalidConfig(`channels[${index}].provider must be one of: ${Array.from(CHANNEL_PROVIDERS).join(", ")}.`);
+  }
+
+  expectStringArray(value.secrets, `channels[${index}].secrets`);
+  validateSecretNames(value.secrets, `channels[${index}].secrets`);
+  validateChannelLimits(value.limits, index);
+  validateChannelBuffer(value.buffer, index);
+
+  if (value.type === "website") {
+    validateWebsiteChannel(value, index);
+    return;
+  }
+
+  if (value.type === "telegram") {
+    validateTelegramChannel(value, index);
+    return;
+  }
+
+  validateWhatsappChannel(value, index);
+}
+
+function validateWebsiteChannel(value: Record<string, unknown>, index: number): void {
+  if (value.provider !== "agentkit") {
+    throw invalidConfig(`channels[${index}].provider must be "agentkit" when type is "website".`);
+  }
+
+  if (!isRecord(value.access) || value.access.mode !== "token") {
+    throw invalidConfig(`channels[${index}].access.mode must be "token" when type is "website".`);
+  }
+
+  expectRequiredSecrets(value.secrets, ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"], `channels[${index}]`);
+}
+
+function validateTelegramChannel(value: Record<string, unknown>, index: number): void {
+  if (value.provider !== "telegram") {
+    throw invalidConfig(`channels[${index}].provider must be "telegram" when type is "telegram".`);
+  }
+
+  expectRequiredSecrets(value.secrets, ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"], `channels[${index}]`);
+
+  if (!Array.isArray(value.allowedUpdates)) {
+    throw invalidConfig(`channels[${index}].allowedUpdates must be an array.`);
+  }
+
+  for (const update of value.allowedUpdates) {
+    if (!TELEGRAM_ALLOWED_UPDATES.has(update as TelegramAllowedUpdate)) {
+      throw invalidConfig(`channels[${index}].allowedUpdates currently supports only "message".`);
+    }
+  }
+}
+
+function validateWhatsappChannel(value: Record<string, unknown>, index: number): void {
+  if (value.type !== "whatsapp") {
+    throw invalidConfig(`channels[${index}].type must be "website", "telegram", or "whatsapp".`);
+  }
+
+  if (value.provider === "zapster") {
+    expectRequiredSecrets(
+      value.secrets,
+      ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"],
+      `channels[${index}]`,
+    );
+    return;
+  }
+
+  if (value.provider === "meta") {
+    expectRequiredSecrets(
+      value.secrets,
+      ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"],
+      `channels[${index}]`,
+    );
+    return;
+  }
+
+  throw invalidConfig(`channels[${index}].provider must be "zapster" or "meta" when type is "whatsapp".`);
+}
+
+function validateChannelLimits(value: unknown, index: number): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!isRecord(value)) {
+    throw invalidConfig(`channels[${index}].limits must be an object when provided.`);
+  }
+
+  for (const field of ["messagesPerDay", "usdPerDay"] as const) {
+    if (
+      value[field] !== undefined &&
+      (typeof value[field] !== "number" || !Number.isFinite(value[field]) || value[field] <= 0)
+    ) {
+      throw invalidConfig(`channels[${index}].limits.${field} must be a positive number when provided.`);
+    }
+  }
+}
+
+function validateChannelBuffer(value: unknown, index: number): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!isRecord(value)) {
+    throw invalidConfig(`channels[${index}].buffer must be an object when provided.`);
+  }
+
+  if (!CHANNEL_BUFFER_MODES.has(value.mode as ChannelBufferMode)) {
+    throw invalidConfig(`channels[${index}].buffer.mode must be "off" or "debounce".`);
+  }
+
+  if (value.mode === "off") {
+    return;
+  }
+
+  for (const field of ["quietWindowMs", "maxWaitMs", "maxMessages", "maxChars"] as const) {
+    if (
+      value[field] === undefined ||
+      typeof value[field] !== "number" ||
+      !Number.isInteger(value[field]) ||
+      value[field] <= 0
+    ) {
+      throw invalidConfig(`channels[${index}].buffer.${field} must be a positive integer.`);
+    }
+  }
+
+  if ((value.maxWaitMs as number) < (value.quietWindowMs as number)) {
+    throw invalidConfig(`channels[${index}].buffer.maxWaitMs must be greater than or equal to quietWindowMs.`);
+  }
+}
+
+function validateSecretNames(secrets: string[], field: string): void {
+  for (const secret of secrets) {
+    if (!SECRET_NAME_PATTERN.test(secret)) {
+      throw invalidConfig(`${field} must contain environment variable names, not secret values.`);
+    }
+  }
+}
+
+function expectRequiredSecrets(value: unknown, requiredSecrets: string[], field: string): void {
+  const declaredSecrets = new Set(Array.isArray(value) ? value : []);
+  const missingSecrets = requiredSecrets.filter((secret) => !declaredSecrets.has(secret));
+
+  if (missingSecrets.length > 0) {
+    throw invalidConfig(`${field}.secrets is missing required secret names: ${missingSecrets.join(", ")}.`);
+  }
+}
+
+function validateDatabaseConfig(value: unknown): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!isRecord(value)) {
+    throw invalidConfig("storage.database must be an object when provided.");
+  }
+
+  if (value.driver !== "none" && value.driver !== "turso") {
+    throw invalidConfig('storage.database.driver must be "none" or "turso".');
+  }
+
+  if (value.schema !== undefined && typeof value.schema !== "string") {
+    throw invalidConfig("storage.database.schema must be a string when provided.");
+  }
+
+  if (value.migrations !== undefined && typeof value.migrations !== "string") {
+    throw invalidConfig("storage.database.migrations must be a string when provided.");
+  }
+}
+
+function validateFilesConfig(value: unknown): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!isRecord(value)) {
+    throw invalidConfig("storage.files must be an object when provided.");
+  }
+
+  if (value.driver !== "none" && value.driver !== "r2") {
+    throw invalidConfig('storage.files.driver must be "none" or "r2".');
+  }
+
+  if (value.bucket !== undefined && typeof value.bucket !== "string") {
+    throw invalidConfig("storage.files.bucket must be a string when provided.");
+  }
+
+  if (value.prefix !== undefined && typeof value.prefix !== "string") {
+    throw invalidConfig("storage.files.prefix must be a string when provided.");
+  }
+
+  if (
+    value.maxUploadBytes !== undefined &&
+    (typeof value.maxUploadBytes !== "number" ||
+      !Number.isInteger(value.maxUploadBytes) ||
+      value.maxUploadBytes <= 0)
+  ) {
+    throw invalidConfig("storage.files.maxUploadBytes must be a positive integer when provided.");
+  }
+}
+
+function validateTool(value: unknown, index: number): asserts value is AgentTool {
+  if (!isRecord(value)) {
+    throw invalidConfig(`tools[${index}] must be an object.`);
+  }
+
+  expectString(value.name, `tools[${index}].name`);
+  expectString(value.description, `tools[${index}].description`);
+
+  if (value.visibility !== undefined && !TOOL_VISIBILITIES.has(value.visibility as ToolVisibility)) {
+    throw invalidConfig(`tools[${index}].visibility must be "user" or "internal" when provided.`);
+  }
+
+  if (!isRecord(value.inputSchema)) {
+    throw invalidConfig(`tools[${index}].inputSchema must be an object.`);
+  }
+
+  if (value.outputSchema !== undefined && !isRecord(value.outputSchema)) {
+    throw invalidConfig(`tools[${index}].outputSchema must be an object when provided.`);
+  }
+
+  if (value.secrets !== undefined) {
+    expectStringArray(value.secrets, `tools[${index}].secrets`);
+  }
+
+  if (value.permissions !== undefined) {
+    expectStringArray(value.permissions, `tools[${index}].permissions`);
+  }
+
+  if (value.timeoutMs !== undefined) {
+    if (typeof value.timeoutMs !== "number" || !Number.isInteger(value.timeoutMs) || value.timeoutMs <= 0) {
+      throw invalidConfig(`tools[${index}].timeoutMs must be a positive integer when provided.`);
+    }
+  }
+
+  if (typeof value.execute !== "function") {
+    throw invalidConfig(`tools[${index}].execute must be a function.`);
+  }
+
+  if (value.render !== undefined && typeof value.render !== "function") {
+    throw invalidConfig(`tools[${index}].render must be a function when provided.`);
+  }
+}
+
+function resolvePath(root: string, path: string): string {
+  return isAbsolute(path) ? path : resolve(root, path);
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    const result = await stat(path);
+    return result.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function invalidConfig(message: string): AgentKitError {
+  return new AgentKitError("invalid_config", `Invalid ${CONFIG_FILE}: ${message}`);
+}
+
+function expectString(value: unknown, field: string): asserts value is string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw invalidConfig(`${field} must be a non-empty string.`);
+  }
+}
+
+function expectStringArray(value: unknown, field: string): asserts value is string[] {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length === 0)) {
+    throw invalidConfig(`${field} must be an array of non-empty strings.`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export async function validateConfigExists(cwd = process.cwd()): Promise<void> {
+  const root = await findAgentCapsuleRoot(cwd);
+  await access(join(root, CONFIG_FILE), constants.R_OK);
+}