@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

package/src/runtime/config.ts

@@ -13,25 +13,41 @@ import type {
   AgentChannel,
   ChannelProvider,
   ChannelType,
+  DiscordChannelMode,
   TelegramAllowedUpdate,
   AgentKnowledgeEmbeddingProvider,
   ChannelBufferMode,
+  AgentIntegration,
+  ChannelAudioMode,
+  TranscriptionProviderName,
+  ChannelReplyRouteConfig,
 } 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 PROVIDERS = new Set<AgentProviderName>(["test", "openai", "openai-codex", "anthropic", "openrouter", "opencode", "opencode-go", "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", "webhook"]);
+const CHANNEL_PROVIDERS = new Set<ChannelProvider>(["agentkit", "telegram", "zapster", "meta", "uazapi", "evolution", "discord", "slack", "generic"]);
 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 CHANNEL_REPLY_PATH_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-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 HTTP_HEADER_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]*$/;
 const moduleDir = dirname(fileURLToPath(import.meta.url));
+let configImportNonce = 0;
 
 export type LoadedAgentCapsule = {
   root: string;
@@ -107,16 +123,37 @@ function resolveLocalStoragePath(root: string, config: AgentConfig): string | un
   return undefined;
 }
 
+// Every import of the config goes through a uniquely named temp module, and
+// Node never evicts imported modules. Re-importing on each request (the dev and
+// container servers load the capsule per request) grows memory without bound,
+// so reuse the import while the config source is unchanged. Edits still reload.
+const configModuleCache = new Map<string, { source: string; value: Promise<unknown> }>();
+
 async function loadConfigModule(configPath: string): Promise<unknown> {
-  const configUrl = pathToFileURL(configPath);
-  configUrl.searchParams.set("t", String(Date.now()));
+  const source = await readFile(configPath, "utf8");
+  const cached = configModuleCache.get(configPath);
+
+  if (cached?.source === source) {
+    return cached.value;
+  }
+
+  const value = importConfigModule(configPath, source);
+  configModuleCache.set(configPath, { source, value });
+  value.catch(() => {
+    if (configModuleCache.get(configPath)?.value === value) {
+      configModuleCache.delete(configPath);
+    }
+  });
+
+  return value;
+}
 
+async function importConfigModule(configPath: string, source: string): Promise<unknown> {
   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(
@@ -127,8 +164,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,
@@ -143,15 +183,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) {
@@ -165,6 +210,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");
@@ -195,8 +245,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)) {
@@ -208,7 +267,9 @@ 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)) {
@@ -227,10 +288,181 @@ 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 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;
@@ -359,7 +591,7 @@ function validateKnowledgeRetrieval(value: unknown): void {
   }
 }
 
-function validateChannels(value: unknown, runtime: AgentRuntime): void {
+function validateChannels(value: unknown, runtime: AgentRuntime, hasTranscriptionConfig: boolean): void {
   if (value === undefined) {
     return;
   }
@@ -375,7 +607,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.`);
@@ -383,9 +615,13 @@ function validateChannels(value: unknown, runtime: AgentRuntime): void {
 
     names.add(channel.name);
   }
+
+  for (const [index, channel] of value.entries()) {
+    validateChannelReplyRoute(channel, index, names);
+  }
 }
 
-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.`);
   }
@@ -408,9 +644,27 @@ function validateChannel(value: unknown, index: number): asserts value is AgentC
 
   expectStringArray(value.secrets, `channels[${index}].secrets`);
   validateSecretNames(value.secrets, `channels[${index}].secrets`);
+  validateChannelReplyTo(value.replyTo, index);
   validateChannelLimits(value.limits, index);
   validateChannelBuffer(value.buffer, index);
 
+  if (value.type === "discord") {
+    validateDiscordChannel(value, index);
+    return;
+  }
+
+  if (value.type === "slack") {
+    validateSlackChannel(value, index);
+    return;
+  }
+
+  if (value.type === "webhook") {
+    validateGenericWebhookChannel(value, index);
+    return;
+  }
+
+  validateChannelAudio(value.audio, index, hasTranscriptionConfig);
+
   if (value.type === "website") {
     validateWebsiteChannel(value, index);
     return;
@@ -424,6 +678,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".`);
@@ -456,11 +735,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", "slack", or "webhook".`);
   }
 
   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", "ZAPSTER_WEBHOOK_TOKEN"],
+      `channels[${index}]`,
+    );
     return;
   }
 
@@ -473,7 +756,205 @@ function validateWhatsappChannel(value: Record<string, unknown>, index: number):
     return;
   }
 
-  throw invalidConfig(`channels[${index}].provider must be "zapster" or "meta" when type is "whatsapp".`);
+  if (value.provider === "uazapi") {
+    expectRequiredSecrets(
+      value.secrets,
+      ["UAZAPI_BASE_URL", "UAZAPI_TOKEN", "UAZAPI_WEBHOOK_TOKEN"],
+      `channels[${index}]`,
+    );
+    return;
+  }
+
+  if (value.provider === "evolution") {
+    expectRequiredSecrets(
+      value.secrets,
+      ["EVOLUTION_API_BASE_URL", "EVOLUTION_API_KEY", "EVOLUTION_INSTANCE_NAME", "EVOLUTION_WEBHOOK_TOKEN"],
+      `channels[${index}]`,
+    );
+    return;
+  }
+
+  throw invalidConfig(`channels[${index}].provider must be "zapster", "meta", "uazapi", or "evolution" 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 validateGenericWebhookChannel(value: Record<string, unknown>, index: number): void {
+  if (value.provider !== "generic") {
+    throw invalidConfig(`channels[${index}].provider must be "generic" when type is "webhook".`);
+  }
+
+  if (value.audio !== undefined) {
+    throw invalidConfig(`channels[${index}].audio is not supported when type is "webhook".`);
+  }
+
+  if (value.direction !== undefined && value.direction !== "inbound" && value.direction !== "outbound") {
+    throw invalidConfig(`channels[${index}].direction must be "inbound" or "outbound" when type is "webhook".`);
+  }
+
+  if (value.direction === "outbound") {
+    if (value.buffer !== undefined) {
+      throw invalidConfig(`channels[${index}].buffer is not supported for outbound webhook channels.`);
+    }
+
+    if (value.replyTo !== undefined) {
+      throw invalidConfig(`channels[${index}].replyTo is not supported for outbound webhook channels.`);
+    }
+
+    expectString(value.urlSecret, `channels[${index}].urlSecret`);
+    validateSecretNames([value.urlSecret], `channels[${index}].urlSecret`);
+    validateGenericWebhookOutputAuth(value.auth, index);
+    expectRequiredSecrets(
+      value.secrets,
+      [value.urlSecret, ...genericWebhookOutputAuthSecrets(value.auth)],
+      `channels[${index}]`,
+    );
+    return;
+  }
+
+  if (value.urlSecret !== undefined || value.auth !== undefined) {
+    throw invalidConfig(`channels[${index}].urlSecret and auth are only supported for outbound webhook channels.`);
+  }
+
+  expectRequiredSecrets(value.secrets, ["AGENTKIT_WEBHOOK_SECRET"], `channels[${index}]`);
+}
+
+function validateChannelReplyTo(value: unknown, index: number): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!isRecord(value)) {
+    throw invalidConfig(`channels[${index}].replyTo must be an object when provided.`);
+  }
+
+  expectString(value.channel, `channels[${index}].replyTo.channel`);
+
+  if (!CHANNEL_NAME_PATTERN.test(value.channel)) {
+    throw invalidConfig(`channels[${index}].replyTo.channel must be a valid channel name.`);
+  }
+
+  if (value.recipientFrom !== undefined) {
+    expectString(value.recipientFrom, `channels[${index}].replyTo.recipientFrom`);
+
+    if (!CHANNEL_REPLY_PATH_PATTERN.test(String(value.recipientFrom).replace(/^payload\./, ""))) {
+      throw invalidConfig(`channels[${index}].replyTo.recipientFrom must be a dotted JSON field path.`);
+    }
+  }
+}
+
+function validateChannelReplyRoute(
+  channel: unknown,
+  index: number,
+  names: Set<string>,
+): void {
+  if (!isRecord(channel) || !isRecord(channel.replyTo)) {
+    return;
+  }
+
+  const replyTo = channel.replyTo as ChannelReplyRouteConfig;
+
+  if (!names.has(replyTo.channel)) {
+    throw invalidConfig(`channels[${index}].replyTo.channel must name another channel in this Agent Capsule.`);
+  }
+
+  if (replyTo.channel === channel.name) {
+    throw invalidConfig(`channels[${index}].replyTo.channel must not point back to the same channel.`);
+  }
+}
+
+function validateGenericWebhookOutputAuth(value: unknown, index: number): void {
+  if (!isRecord(value)) {
+    throw invalidConfig(`channels[${index}].auth must be an object for outbound webhook channels.`);
+  }
+
+  if (value.type === "none") {
+    return;
+  }
+
+  if (value.type === "bearer") {
+    expectString(value.tokenSecret, `channels[${index}].auth.tokenSecret`);
+    validateSecretNames([value.tokenSecret], `channels[${index}].auth.tokenSecret`);
+    return;
+  }
+
+  if (value.type === "header") {
+    expectString(value.headerName, `channels[${index}].auth.headerName`);
+
+    if (!HTTP_HEADER_NAME_PATTERN.test(value.headerName)) {
+      throw invalidConfig(`channels[${index}].auth.headerName must be an HTTP header name.`);
+    }
+
+    expectString(value.valueSecret, `channels[${index}].auth.valueSecret`);
+    validateSecretNames([value.valueSecret], `channels[${index}].auth.valueSecret`);
+    return;
+  }
+
+  if (value.type === "hmac") {
+    if (value.headerName !== undefined) {
+      expectString(value.headerName, `channels[${index}].auth.headerName`);
+
+      if (!HTTP_HEADER_NAME_PATTERN.test(value.headerName)) {
+        throw invalidConfig(`channels[${index}].auth.headerName must be an HTTP header name.`);
+      }
+    }
+
+    expectString(value.secret, `channels[${index}].auth.secret`);
+    validateSecretNames([value.secret], `channels[${index}].auth.secret`);
+    return;
+  }
+
+  throw invalidConfig(`channels[${index}].auth.type must be "none", "bearer", "header", or "hmac".`);
+}
+
+function genericWebhookOutputAuthSecrets(value: unknown): string[] {
+  if (!isRecord(value)) {
+    return [];
+  }
+
+  if (value.type === "bearer" && typeof value.tokenSecret === "string") {
+    return [value.tokenSecret];
+  }
+
+  if (value.type === "header" && typeof value.valueSecret === "string") {
+    return [value.valueSecret];
+  }
+
+  if (value.type === "hmac" && typeof value.secret === "string") {
+    return [value.secret];
+  }
+
+  return [];
 }
 
 function validateChannelLimits(value: unknown, index: number): void {
@@ -536,6 +1017,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));
@@ -620,6 +1111,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) {