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

package/src/runtime/config.ts

@@ -13,21 +13,38 @@ import type {
   AgentChannel,
   ChannelProvider,
   ChannelType,
+  DiscordChannelMode,
   TelegramAllowedUpdate,
+  AgentKnowledgeEmbeddingProvider,
+  ChannelBufferMode,
+  AgentIntegration,
+  ChannelAudioMode,
+  TranscriptionProviderName,
 } from "../index";
+import { MANAGED_COMPOSIO_TOOL_NAME } from "./integrations/composio";
 import { AgentKitError } from "./errors";
+import { isValidTimeZone } from "./prompt-context";
 
 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_TYPES = new Set<ChannelType>(["website", "telegram", "whatsapp", "discord", "slack"]);
+const CHANNEL_PROVIDERS = new Set<ChannelProvider>(["agentkit", "telegram", "zapster", "meta", "discord", "slack"]);
+const CHANNEL_BUFFER_MODES = new Set<ChannelBufferMode>(["off", "debounce"]);
+const CHANNEL_AUDIO_MODES = new Set<ChannelAudioMode>(["off", "reject", "transcribe"]);
+const DISCORD_CHANNEL_MODES = new Set<DiscordChannelMode>(["interactions", "bot"]);
 const TELEGRAM_ALLOWED_UPDATES = new Set<TelegramAllowedUpdate>(["message"]);
+const KNOWLEDGE_EMBEDDING_PROVIDERS = new Set<AgentKnowledgeEmbeddingProvider>(["none", "test", "openai"]);
+const TRANSCRIPTION_PROVIDERS = new Set<TranscriptionProviderName>(["test", "openai", "groq"]);
 const CHANNEL_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const INTEGRATION_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const COMPOSIO_TOOLKIT_PATTERN = /^[a-z][a-z0-9_-]*$/;
+const COMPOSIO_TOOL_SLUG_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 const SECRET_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 const moduleDir = dirname(fileURLToPath(import.meta.url));
+let configImportNonce = 0;
 
 export type LoadedAgentCapsule = {
   root: string;
@@ -104,15 +121,13 @@ function resolveLocalStoragePath(root: string, config: AgentConfig): string | un
 }
 
 async function loadConfigModule(configPath: string): Promise<unknown> {
-  const configUrl = pathToFileURL(configPath);
-  configUrl.searchParams.set("t", String(Date.now()));
+  const source = await readFile(configPath, "utf8");
 
   try {
-    const module = (await import(configUrl.href)) as { default?: unknown };
-    return module.default;
+    return await importConfigSource(configPath, source);
   } catch (error) {
     if (isMissingAgentKitSelfImport(error)) {
-      return loadConfigModuleWithLocalSelfImport(configPath, error);
+      return loadConfigModuleWithLocalSelfImport(configPath, source, error);
     }
 
     throw new AgentKitError(
@@ -123,8 +138,11 @@ async function loadConfigModule(configPath: string): Promise<unknown> {
   }
 }
 
-async function loadConfigModuleWithLocalSelfImport(configPath: string, originalError: unknown): Promise<unknown> {
-  const source = await readFile(configPath, "utf8");
+async function loadConfigModuleWithLocalSelfImport(
+  configPath: string,
+  source: string,
+  originalError: unknown,
+): Promise<unknown> {
   const localAgentKitUrl = pathToFileURL(resolve(moduleDir, "../index.ts")).href;
   const patchedSource = source.replace(
     /from\s+["']@andreprado\/agentkit["']/g,
@@ -139,15 +157,20 @@ async function loadConfigModuleWithLocalSelfImport(configPath: string, originalE
     );
   }
 
+  return importConfigSource(configPath, patchedSource);
+}
+
+async function importConfigSource(configPath: string, source: string): Promise<unknown> {
+  const nonce = nextConfigImportNonce();
   const tempConfigPath = join(
     dirname(configPath),
-    `.agentkit.config.loader-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.ts`,
+    `.agentkit.config.loader-${process.pid}-${nonce}-${Math.random().toString(16).slice(2)}.ts`,
   );
 
   try {
-    await writeFile(tempConfigPath, patchedSource);
+    await writeFile(tempConfigPath, source);
     const configUrl = pathToFileURL(tempConfigPath);
-    configUrl.searchParams.set("t", String(Date.now()));
+    configUrl.searchParams.set("t", nonce);
     const module = (await import(configUrl.href)) as { default?: unknown };
     return module.default;
   } catch (error) {
@@ -161,6 +184,11 @@ async function loadConfigModuleWithLocalSelfImport(configPath: string, originalE
   }
 }
 
+function nextConfigImportNonce(): string {
+  configImportNonce += 1;
+  return `${Date.now()}-${configImportNonce}`;
+}
+
 function isMissingAgentKitSelfImport(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
   return message.includes("@andreprado/agentkit");
@@ -191,8 +219,17 @@ function validateAgentConfig(value: unknown): asserts value is AgentConfig {
     throw invalidConfig('provider.model must be "fake" when provider.name is "test".');
   }
 
+  if (value.timeZone !== undefined) {
+    expectString(value.timeZone, "timeZone");
+
+    if (!isValidTimeZone(value.timeZone)) {
+      throw invalidConfig('timeZone must be a valid IANA time zone such as "UTC" or "America/New_York".');
+    }
+  }
+
   expectString(value.instructions, "instructions");
   expectStringArray(value.secrets, "secrets");
+  validateSecretNames(value.secrets, "secrets");
 
   if (value.tools !== undefined) {
     if (!Array.isArray(value.tools)) {
@@ -204,7 +241,10 @@ function validateAgentConfig(value: unknown): asserts value is AgentConfig {
     }
   }
 
-  validateChannels(value.channels, value.runtime as AgentRuntime);
+  validateIntegrations(value.integrations, value.runtime as AgentRuntime, value.tools);
+  validateTranscriptionConfig(value.transcription);
+  validateChannels(value.channels, value.runtime as AgentRuntime, Boolean(value.transcription));
+  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".');
@@ -222,11 +262,310 @@ function validateAgentConfig(value: unknown): asserts value is AgentConfig {
     throw invalidConfig("storage.path must be a string when provided.");
   }
 
+  if (value.storage.driver === "sqlite" && typeof value.storage.path !== "string") {
+    throw invalidConfig('storage.path is required when storage.driver is "sqlite".');
+  }
+
   validateDatabaseConfig(value.storage.database);
   validateFilesConfig(value.storage.files);
 }
 
-function validateChannels(value: unknown, runtime: AgentRuntime): void {
+function validateIntegrations(
+  value: unknown,
+  runtime: AgentRuntime,
+  tools: AgentConfig["tools"] = [],
+): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw invalidConfig("integrations must be an array when provided.");
+  }
+
+  if (value.length > 0 && runtime !== "edge") {
+    throw invalidConfig('managed integrations require runtime: "edge". Use BYO defineTool wrappers for local-only integrations.');
+  }
+
+  let composioCount = 0;
+
+  for (const [index, integration] of value.entries()) {
+    if (!isRecord(integration)) {
+      throw invalidConfig(`integrations[${index}] must be an object.`);
+    }
+
+    if (integration.provider !== "composio" || integration.type !== "composio" || integration.mode !== "managed") {
+      throw invalidConfig(`integrations[${index}] must be composioManaged({...}) or { type: "composio", provider: "composio", mode: "managed", ... }.`);
+    }
+
+    composioCount += 1;
+    validateComposioManagedIntegration(integration as unknown as AgentIntegration, index);
+  }
+
+  if (composioCount > 1) {
+    throw invalidConfig("Only one managed Composio integration is supported per agent.");
+  }
+
+  const hasExplicitComposioTools = value.some(
+    (integration) => isRecord(integration) && integration.provider === "composio" && isRecord(integration.tools),
+  );
+
+  if (hasExplicitComposioTools && tools.some((tool) => isRecord(tool) && tool.name === MANAGED_COMPOSIO_TOOL_NAME)) {
+    throw invalidConfig(`tools must not declare reserved managed Composio tool name "${MANAGED_COMPOSIO_TOOL_NAME}".`);
+  }
+}
+
+function validateComposioManagedIntegration(value: AgentIntegration, index: number): void {
+  expectString(value.name, `integrations[${index}].name`);
+
+  if (!INTEGRATION_NAME_PATTERN.test(value.name)) {
+    throw invalidConfig(`integrations[${index}].name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.`);
+  }
+
+  if (!Array.isArray(value.toolkits) || value.toolkits.length === 0) {
+    throw invalidConfig(`integrations[${index}].toolkits must include at least one Composio toolkit slug.`);
+  }
+
+  const toolkits = new Set<string>();
+
+  for (const [toolkitIndex, toolkit] of value.toolkits.entries()) {
+    expectString(toolkit, `integrations[${index}].toolkits[${toolkitIndex}]`);
+
+    if (!COMPOSIO_TOOLKIT_PATTERN.test(toolkit)) {
+      throw invalidConfig(`integrations[${index}].toolkits[${toolkitIndex}] must be a lowercase Composio toolkit slug.`);
+    }
+
+    if (toolkits.has(toolkit)) {
+      throw invalidConfig(`integrations[${index}].toolkits must not contain duplicates.`);
+    }
+
+    toolkits.add(toolkit);
+  }
+
+  if (value.tools !== undefined) {
+    if (!isRecord(value.tools)) {
+      throw invalidConfig(`integrations[${index}].tools must be an object when provided.`);
+    }
+
+    for (const [toolkit, tools] of Object.entries(value.tools)) {
+      if (!toolkits.has(toolkit)) {
+        throw invalidConfig(`integrations[${index}].tools.${toolkit} must reference a toolkit listed in integrations[${index}].toolkits.`);
+      }
+
+      if (!Array.isArray(tools) || tools.length === 0) {
+        throw invalidConfig(`integrations[${index}].tools.${toolkit} must include at least one Composio action slug.`);
+      }
+
+      const seenTools = new Set<string>();
+
+      for (const [toolIndex, tool] of tools.entries()) {
+        expectString(tool, `integrations[${index}].tools.${toolkit}[${toolIndex}]`);
+
+        if (!COMPOSIO_TOOL_SLUG_PATTERN.test(tool)) {
+          throw invalidConfig(`integrations[${index}].tools.${toolkit}[${toolIndex}] must be an uppercase Composio action slug.`);
+        }
+
+        if (seenTools.has(tool)) {
+          throw invalidConfig(`integrations[${index}].tools.${toolkit} must not contain duplicates.`);
+        }
+
+        seenTools.add(tool);
+      }
+    }
+  }
+
+  if (value.tags !== undefined) {
+    validateIntegrationTags(value.tags, `integrations[${index}].tags`);
+  }
+
+  if (value.confirmExternalWrites !== undefined && typeof value.confirmExternalWrites !== "boolean") {
+    throw invalidConfig(`integrations[${index}].confirmExternalWrites must be a boolean when provided.`);
+  }
+}
+
+function validateIntegrationTags(value: unknown, label: string): void {
+  if (!isRecord(value)) {
+    throw invalidConfig(`${label} must be an object when provided.`);
+  }
+
+  if (value.enable !== undefined) {
+    expectStringArray(value.enable, `${label}.enable`);
+  }
+
+  if (value.disable !== undefined) {
+    expectStringArray(value.disable, `${label}.disable`);
+  }
+}
+
+function validateTranscriptionConfig(value: unknown): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!isRecord(value)) {
+    throw invalidConfig("transcription must be an object when provided.");
+  }
+
+  if (!TRANSCRIPTION_PROVIDERS.has(value.provider as TranscriptionProviderName)) {
+    throw invalidConfig(`transcription.provider must be one of: ${Array.from(TRANSCRIPTION_PROVIDERS).join(", ")}.`);
+  }
+
+  expectString(value.model, "transcription.model");
+
+  if (value.secret !== undefined) {
+    expectString(value.secret, "transcription.secret");
+    validateSecretNames([value.secret], "transcription.secret");
+  }
+
+  if (value.language !== undefined) {
+    expectString(value.language, "transcription.language");
+  }
+
+  if (value.prompt !== undefined) {
+    expectString(value.prompt, "transcription.prompt");
+  }
+
+  if (value.limits !== undefined) {
+    if (!isRecord(value.limits)) {
+      throw invalidConfig("transcription.limits must be an object when provided.");
+    }
+
+    validateOptionalPositiveInteger(value.limits.maxDurationSeconds, "transcription.limits.maxDurationSeconds");
+    validateOptionalPositiveInteger(value.limits.maxBytes, "transcription.limits.maxBytes");
+  }
+
+  validateOptionalPositiveInteger(value.rawAudioTtlSeconds, "transcription.rawAudioTtlSeconds");
+}
+
+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, hasTranscriptionConfig: boolean): void {
   if (value === undefined) {
     return;
   }
@@ -242,7 +581,7 @@ function validateChannels(value: unknown, runtime: AgentRuntime): void {
   const names = new Set<string>();
 
   for (const [index, channel] of value.entries()) {
-    validateChannel(channel, index);
+    validateChannel(channel, index, hasTranscriptionConfig);
 
     if (names.has(channel.name)) {
       throw invalidConfig(`channels[${index}].name must be unique within the Agent Capsule.`);
@@ -252,7 +591,7 @@ function validateChannels(value: unknown, runtime: AgentRuntime): void {
   }
 }
 
-function validateChannel(value: unknown, index: number): asserts value is AgentChannel {
+function validateChannel(value: unknown, index: number, hasTranscriptionConfig: boolean): asserts value is AgentChannel {
   if (!isRecord(value)) {
     throw invalidConfig(`channels[${index}] must be an object.`);
   }
@@ -276,6 +615,19 @@ function validateChannel(value: unknown, index: number): asserts value is AgentC
   expectStringArray(value.secrets, `channels[${index}].secrets`);
   validateSecretNames(value.secrets, `channels[${index}].secrets`);
   validateChannelLimits(value.limits, index);
+  validateChannelBuffer(value.buffer, index);
+
+  if (value.type === "discord") {
+    validateDiscordChannel(value, index);
+    return;
+  }
+
+  if (value.type === "slack") {
+    validateSlackChannel(value, index);
+    return;
+  }
+
+  validateChannelAudio(value.audio, index, hasTranscriptionConfig);
 
   if (value.type === "website") {
     validateWebsiteChannel(value, index);
@@ -290,6 +642,31 @@ function validateChannel(value: unknown, index: number): asserts value is AgentC
   validateWhatsappChannel(value, index);
 }
 
+function validateChannelAudio(value: unknown, index: number, hasTranscriptionConfig: boolean): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!isRecord(value)) {
+    throw invalidConfig(`channels[${index}].audio must be an object when provided.`);
+  }
+
+  if (!CHANNEL_AUDIO_MODES.has(value.mode as ChannelAudioMode)) {
+    throw invalidConfig(`channels[${index}].audio.mode must be "off", "reject", or "transcribe".`);
+  }
+
+  if (value.mode === "transcribe" && !hasTranscriptionConfig) {
+    throw invalidConfig(`channels[${index}].audio.mode "transcribe" requires top-level transcription config.`);
+  }
+
+  if (value.mode !== "off") {
+    expectString(value.fallbackMessage, `channels[${index}].audio.fallbackMessage`);
+  }
+
+  validateOptionalPositiveInteger(value.maxDurationSeconds, `channels[${index}].audio.maxDurationSeconds`);
+  validateOptionalPositiveInteger(value.maxBytes, `channels[${index}].audio.maxBytes`);
+}
+
 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".`);
@@ -322,11 +699,15 @@ function validateTelegramChannel(value: Record<string, unknown>, index: number):
 
 function validateWhatsappChannel(value: Record<string, unknown>, index: number): void {
   if (value.type !== "whatsapp") {
-    throw invalidConfig(`channels[${index}].type must be "website", "telegram", or "whatsapp".`);
+    throw invalidConfig(`channels[${index}].type must be "website", "telegram", "whatsapp", "discord", or "slack".`);
   }
 
   if (value.provider === "zapster") {
-    expectRequiredSecrets(value.secrets, ["ZAPSTER_API_KEY", "ZAPSTER_WEBHOOK_SECRET"], `channels[${index}]`);
+    expectRequiredSecrets(
+      value.secrets,
+      ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"],
+      `channels[${index}]`,
+    );
     return;
   }
 
@@ -342,6 +723,38 @@ function validateWhatsappChannel(value: Record<string, unknown>, index: number):
   throw invalidConfig(`channels[${index}].provider must be "zapster" or "meta" when type is "whatsapp".`);
 }
 
+function validateDiscordChannel(value: Record<string, unknown>, index: number): void {
+  if (value.provider !== "discord") {
+    throw invalidConfig(`channels[${index}].provider must be "discord" when type is "discord".`);
+  }
+
+  if (value.mode !== undefined && !DISCORD_CHANNEL_MODES.has(value.mode as DiscordChannelMode)) {
+    throw invalidConfig(`channels[${index}].mode must be "interactions" or "bot" when type is "discord".`);
+  }
+
+  if (value.audio !== undefined) {
+    throw invalidConfig(`channels[${index}].audio is not supported when type is "discord".`);
+  }
+
+  expectRequiredSecrets(
+    value.secrets,
+    value.mode === "bot" ? ["DISCORD_BOT_TOKEN"] : ["DISCORD_PUBLIC_KEY"],
+    `channels[${index}]`,
+  );
+}
+
+function validateSlackChannel(value: Record<string, unknown>, index: number): void {
+  if (value.provider !== "slack") {
+    throw invalidConfig(`channels[${index}].provider must be "slack" when type is "slack".`);
+  }
+
+  if (value.audio !== undefined) {
+    throw invalidConfig(`channels[${index}].audio is not supported when type is "slack".`);
+  }
+
+  expectRequiredSecrets(value.secrets, ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"], `channels[${index}]`);
+}
+
 function validateChannelLimits(value: unknown, index: number): void {
   if (value === undefined) {
     return;
@@ -361,6 +774,39 @@ function validateChannelLimits(value: unknown, index: number): void {
   }
 }
 
+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)) {
@@ -369,6 +815,16 @@ function validateSecretNames(secrets: string[], field: string): void {
   }
 }
 
+function validateOptionalPositiveInteger(value: unknown, field: string): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw invalidConfig(`${field} must be a positive integer when provided.`);
+  }
+}
+
 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));
@@ -394,6 +850,10 @@ function validateDatabaseConfig(value: unknown): void {
   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 {
@@ -449,6 +909,7 @@ function validateTool(value: unknown, index: number): asserts value is AgentTool
 
   if (value.secrets !== undefined) {
     expectStringArray(value.secrets, `tools[${index}].secrets`);
+    validateSecretNames(value.secrets, `tools[${index}].secrets`);
   }
 
   if (value.permissions !== undefined) {
@@ -464,6 +925,10 @@ function validateTool(value: unknown, index: number): asserts value is AgentTool
   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 {