@andreprado/agentkit 0.1.0-alpha.22 → 0.1.0-alpha.24

package/src/runtime/channels.ts

@@ -122,6 +122,9 @@ export type ChannelWebhookResponse = {
 
 export type ChannelSendInput = ChannelAdapterId & {
   channelId: string;
+  channel?: AgentChannel;
+  jobId?: string;
+  deliveryId?: string;
   conversationId: string;
   externalIdentity: ChannelExternalIdentity;
   replyTarget?: ChannelReplyTarget;

package/src/runtime/config.ts

@@ -20,6 +20,7 @@ import type {
   AgentIntegration,
   ChannelAudioMode,
   TranscriptionProviderName,
+  ChannelReplyRouteConfig,
 } from "../index";
 import { MANAGED_COMPOSIO_TOOL_NAME } from "./integrations/composio";
 import { AgentKitError } from "./errors";
@@ -39,10 +40,12 @@ 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;
 
@@ -589,6 +592,10 @@ function validateChannels(value: unknown, runtime: AgentRuntime, hasTranscriptio
 
     names.add(channel.name);
   }
+
+  for (const [index, channel] of value.entries()) {
+    validateChannelReplyRoute(channel, index, names);
+  }
 }
 
 function validateChannel(value: unknown, index: number, hasTranscriptionConfig: boolean): asserts value is AgentChannel {
@@ -614,6 +621,7 @@ function validateChannel(value: unknown, index: number, hasTranscriptionConfig:
 
   expectStringArray(value.secrets, `channels[${index}].secrets`);
   validateSecretNames(value.secrets, `channels[${index}].secrets`);
+  validateChannelReplyTo(value.replyTo, index);
   validateChannelLimits(value.limits, index);
   validateChannelBuffer(value.buffer, index);
 
@@ -787,9 +795,145 @@ function validateGenericWebhookChannel(value: Record<string, unknown>, index: nu
     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 {
   if (value === undefined) {
     return;

package/src/runtime/dev-server.ts

@@ -564,11 +564,23 @@ async function handlePortableChannel(
       conversationId,
       signal: request.signal,
     });
+    const routedReply = channel.replyTo
+      ? await sendDevChannelReply({
+          capsule,
+          sourceChannel: channel,
+          sourceEvent: event,
+          rawBody,
+          conversationId: result.conversationId,
+          message: result.message.content,
+        })
+      : null;
+
     deliveries.push({
       state: "sent",
       dedupeKey: event.dedupeKey,
       conversationId: result.conversationId,
       message: result.message,
+      ...(routedReply ? { outbound: routedReply } : {}),
     });
   }
 
@@ -579,6 +591,118 @@ async function handlePortableChannel(
   return jsonResponse({ deliveries });
 }
 
+async function sendDevChannelReply(input: {
+  capsule: LoadedAgentCapsule;
+  sourceChannel: AgentChannel;
+  sourceEvent: Awaited<ReturnType<ChannelAdapter["normalizeInbound"]>>[number];
+  rawBody: string;
+  conversationId: string;
+  message: string;
+}) {
+  const replyTo = input.sourceChannel.replyTo;
+
+  if (!replyTo) {
+    return null;
+  }
+
+  const target = (input.capsule.config.channels ?? []).find((channel) => channel.name === replyTo.channel);
+
+  if (!target) {
+    throw new AgentKitError("channel_not_found", `Reply target channel "${replyTo.channel}" was not found.`);
+  }
+
+  if (target.type === "webhook" && target.direction !== "outbound") {
+    throw new AgentKitError("channel_payload_invalid", `Reply target channel "${replyTo.channel}" is inbound-only.`);
+  }
+
+  const recipient = replyTo.recipientFrom ? readDevJsonPathScalar(input.rawBody, replyTo.recipientFrom) : null;
+
+  if (replyTo.recipientFrom && !recipient) {
+    throw new AgentKitError("channel_payload_invalid", `Reply route recipientFrom "${replyTo.recipientFrom}" did not resolve to a non-empty value.`);
+  }
+
+  const externalIdentity = recipient
+    ? recipientIdentityForDevChannel(target, recipient)
+    : input.sourceEvent.externalIdentity.key;
+
+  const targetAdapter = adapterForChannel(target.type, target.provider);
+  const secrets = await resolveChannelSecrets(input.capsule.root, target);
+
+  return targetAdapter.sendMessage({
+    type: target.type,
+    provider: target.provider,
+    channelId: target.name,
+    channel: target,
+    conversationId: input.conversationId,
+    externalIdentity: {
+      key: externalIdentity,
+    },
+    message: {
+      role: "assistant",
+      contentType: "text",
+      content: input.message,
+    },
+    secrets,
+  });
+}
+
+function recipientIdentityForDevChannel(channel: AgentChannel, recipient: string): string {
+  if (channel.type === "whatsapp") {
+    const prefix = `whatsapp:${channel.provider}:contact:`;
+    return recipient.startsWith(prefix) ? recipient : `${prefix}${recipient}`;
+  }
+
+  if (channel.type === "telegram") {
+    return recipient.includes(":chat:") ? recipient : `telegram:reply:chat:${recipient}`;
+  }
+
+  if (channel.type === "webhook" && channel.direction === "outbound") {
+    return recipient.startsWith("webhook:generic:") ? recipient : `webhook:generic:recipient:${recipient}`;
+  }
+
+  if (channel.type === "website") {
+    return recipient.startsWith("website:") ? recipient : `website:reply:${createHash("sha256").update(recipient).digest("hex").slice(0, 32)}`;
+  }
+
+  throw new AgentKitError(
+    "channel_payload_invalid",
+    `Reply target ${channel.type}/${channel.provider} requires a provider-native reply target and cannot use recipientFrom.`,
+  );
+}
+
+function readDevJsonPathScalar(rawBody: string, path: string): string | undefined {
+  let value: unknown;
+
+  try {
+    value = JSON.parse(rawBody) as unknown;
+  } catch {
+    return undefined;
+  }
+
+  for (const segment of path.replace(/^payload\./, "").split(".")) {
+    if (!isRecord(value)) {
+      return undefined;
+    }
+
+    value = value[segment];
+  }
+
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+
+  if (typeof value === "boolean") {
+    return String(value);
+  }
+
+  return undefined;
+}
+
 async function processDevChannelMessage(
   capsule: LoadedAgentCapsule,
   adapter: ChannelAdapter,
@@ -1218,7 +1342,13 @@ function discordLocalInteractionResponse(
 
 async function resolveChannelSecrets(root: string, channel: AgentChannel): Promise<Record<string, string>> {
   const env = await loadCapsuleEnv(root);
-  return Object.fromEntries(channel.secrets.map((name) => [name, env[name] ?? ""]));
+  const secrets = Object.fromEntries(channel.secrets.map((name) => [name, env[name] ?? ""]));
+
+  if (env.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN = "1";
+  }
+
+  return secrets;
 }
 
 function relativePath(root: string, path: string): string {

package/src/runtime/inspect.ts

@@ -101,9 +101,16 @@ export type AgentInspectChannel = {
   name: string;
   type: AgentChannel["type"];
   provider: AgentChannel["provider"];
+  direction?: Extract<AgentChannel, { type: "webhook" }>["direction"];
   secrets: string[];
   buffer?: AgentChannel["buffer"];
   audio?: AgentChannel["audio"];
+  replyTo?: Extract<AgentChannel, { replyTo?: unknown }>["replyTo"];
+  urlSecret?: string;
+  auth?: {
+    type: string;
+    headerName?: string;
+  };
 };
 
 export type AgentInspectSkills = {
@@ -209,9 +216,20 @@ export function buildInspectState(
       name: channel.name,
       type: channel.type,
       provider: channel.provider,
+      ...("direction" in channel && channel.direction ? { direction: channel.direction } : {}),
       secrets: [...channel.secrets],
       ...(channel.buffer ? { buffer: channel.buffer } : {}),
       ...(channel.audio ? { audio: channel.audio } : {}),
+      ...(channel.replyTo ? { replyTo: channel.replyTo } : {}),
+      ...("urlSecret" in channel && channel.urlSecret ? { urlSecret: channel.urlSecret } : {}),
+      ...("auth" in channel && channel.auth
+        ? {
+            auth: {
+              type: channel.auth.type,
+              ...("headerName" in channel.auth && channel.auth.headerName ? { headerName: channel.auth.headerName } : {}),
+            },
+          }
+        : {}),
     })),
     transcription: {
       enabled: transcription.enabled,

package/src/runtime/targets/cloudflare/build.ts

@@ -466,10 +466,32 @@ export function webhookChannel(input) {
   return {
     type: "webhook",
     provider: "generic",
+    direction: "inbound",
     name: input.name,
     secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBHOOK_SECRET"], "generic webhook channel"),
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "generic webhook channel") } : {}),
+    ...(input.replyTo ? { replyTo: normalizeChannelReplyRoute(input.replyTo, "generic webhook channel") } : {}),
+  };
+}
+
+export function webhookOutputChannel(input) {
+  const auth = normalizeGenericWebhookOutputAuth(input.auth ?? { type: "none" }, "generic webhook output channel");
+  const requiredSecrets = [
+    input.urlSecret,
+    ...genericWebhookOutputAuthSecrets(auth),
+    ...(input.secrets ?? []),
+  ];
+
+  return {
+    type: "webhook",
+    provider: "generic",
+    direction: "outbound",
+    name: input.name,
+    urlSecret: normalizeSecretName(input.urlSecret, "generic webhook output channel urlSecret"),
+    auth,
+    secrets: normalizeChannelSecrets(requiredSecrets, "generic webhook output channel"),
+    ...(input.limits ? { limits: input.limits } : {}),
   };
 }
 
@@ -493,14 +515,100 @@ function normalizeChannelSecrets(secrets, context) {
   const uniqueSecrets = new Set();
 
   for (const secret of secrets) {
-    if (!/^[A-Z_][A-Z0-9_]*$/.test(secret)) {
-      throw new Error(\`\${context} secrets must be environment variable names, not secret values.\`);
+    uniqueSecrets.add(normalizeSecretName(secret, \`\${context} secrets\`));
+  }
+
+  return Array.from(uniqueSecrets).sort();
+}
+
+function normalizeSecretName(secret, context) {
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(secret)) {
+    if (context.endsWith("secrets")) {
+      throw new Error(\`\${context} must be environment variable names, not secret values.\`);
     }
 
-    uniqueSecrets.add(secret);
+    throw new Error(\`\${context} must be an environment variable name, not a secret value.\`);
   }
 
-  return Array.from(uniqueSecrets).sort();
+  return secret;
+}
+
+function normalizeChannelReplyRoute(input, context) {
+  const channel = input.channel.trim();
+
+  if (!/^[a-z][a-z0-9-]*$/.test(channel)) {
+    throw new Error(\`\${context} replyTo.channel must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.\`);
+  }
+
+  return {
+    channel,
+    ...(input.recipientFrom ? { recipientFrom: normalizeJsonPath(input.recipientFrom, \`\${context} replyTo.recipientFrom\`) } : {}),
+  };
+}
+
+function normalizeJsonPath(value, context) {
+  const path = value.trim().replace(/^payload\\./, "");
+
+  if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(path)) {
+    throw new Error(\`\${context} must be a dotted JSON field path such as "phone" or "customer.phone".\`);
+  }
+
+  return path;
+}
+
+function normalizeGenericWebhookOutputAuth(auth, context) {
+  if (auth.type === "none") {
+    return { type: "none" };
+  }
+
+  if (auth.type === "bearer") {
+    return {
+      type: "bearer",
+      tokenSecret: normalizeSecretName(auth.tokenSecret, \`\${context} auth.tokenSecret\`),
+    };
+  }
+
+  if (auth.type === "header") {
+    if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(auth.headerName)) {
+      throw new Error(\`\${context} auth.headerName must be an HTTP header name.\`);
+    }
+
+    return {
+      type: "header",
+      headerName: auth.headerName,
+      valueSecret: normalizeSecretName(auth.valueSecret, \`\${context} auth.valueSecret\`),
+    };
+  }
+
+  if (auth.type === "hmac") {
+    if (auth.headerName !== undefined && !/^[A-Za-z][A-Za-z0-9-]*$/.test(auth.headerName)) {
+      throw new Error(\`\${context} auth.headerName must be an HTTP header name.\`);
+    }
+
+    return {
+      type: "hmac",
+      secret: normalizeSecretName(auth.secret, \`\${context} auth.secret\`),
+      ...(auth.headerName ? { headerName: auth.headerName } : {}),
+    };
+  }
+
+  throw new Error(\`\${context} auth.type must be "none", "bearer", "header", or "hmac".\`);
+}
+
+function genericWebhookOutputAuthSecrets(auth) {
+  if (auth.type === "bearer") {
+    return [auth.tokenSecret];
+  }
+
+  if (auth.type === "header") {
+    return [auth.valueSecret];
+  }
+
+  if (auth.type === "hmac") {
+    return [auth.secret];
+  }
+
+  return [];
 }
 
 function normalizeIntegrationName(value, context) {