@andreprado/agentkit 0.1.0-alpha.4 → 0.1.0-alpha.6

package/src/runtime/config.ts

@@ -14,6 +14,8 @@ import type {
   ChannelProvider,
   ChannelType,
   TelegramAllowedUpdate,
+  AgentKnowledgeEmbeddingProvider,
+  ChannelBufferMode,
 } from "../index";
 import { AgentKitError } from "./errors";
 
@@ -24,7 +26,9 @@ 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));
@@ -205,6 +209,7 @@ function validateAgentConfig(value: unknown): asserts value is AgentConfig {
   }
 
   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".');
@@ -226,6 +231,134 @@ function validateAgentConfig(value: unknown): asserts value is AgentConfig {
   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;
@@ -276,6 +409,7 @@ 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 === "website") {
     validateWebsiteChannel(value, index);
@@ -361,6 +495,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)) {

package/src/runtime/core/manifest.ts

@@ -2,6 +2,8 @@ import { relative, resolve } from "node:path";
 
 import type { AgentConfig, AgentTool } from "../../index";
 import type { LoadedAgentCapsule } from "../config";
+import { resolveKnowledgeConfig } from "../knowledge/config";
+import { KNOWLEDGE_SEARCH_TOOL_NAME } from "../knowledge/tool";
 
 export type ManifestSchema = {
   source: string;
@@ -25,6 +27,25 @@ export type SharedAgentManifest = {
     timeoutMs: number | null;
   }>;
   channels: NonNullable<AgentConfig["channels"]>;
+  knowledge: {
+    enabled: boolean;
+    sources: Array<{
+      kind: "file" | "url";
+      value: string;
+      title: string | null;
+    }>;
+    embedding: {
+      provider: string;
+      model: string | null;
+      dimensions: number | null;
+      secret: string | null;
+    };
+    retrieval: {
+      topK: number;
+      hybrid: boolean;
+    };
+    internalTool: string | null;
+  };
   access: AgentConfig["access"];
   storage: {
     driver: AgentConfig["storage"]["driver"];
@@ -57,6 +78,7 @@ export function buildSharedAgentManifest(
   const requiredSecrets = new Set(capsule.config.secrets);
   const database = buildDatabaseManifest(capsule, options.databaseSchema ?? null);
   const files = buildFilesManifest(capsule);
+  const knowledge = resolveKnowledgeConfig(capsule.config);
 
   if (capsule.config.access.mode === "private") {
     requiredSecrets.add("AGENTKIT_PRIVATE_TOKEN");
@@ -75,6 +97,10 @@ export function buildSharedAgentManifest(
     requiredSecrets.add("TURSO_AUTH_TOKEN");
   }
 
+  if (knowledge.embedding.secret) {
+    requiredSecrets.add(knowledge.embedding.secret);
+  }
+
   for (const tool of capsule.config.tools ?? []) {
     for (const secret of tool.secrets ?? []) {
       requiredSecrets.add(secret);
@@ -104,6 +130,17 @@ export function buildSharedAgentManifest(
       timeoutMs: tool.timeoutMs ?? null,
     })),
     channels: capsule.config.channels ?? [],
+    knowledge: {
+      enabled: knowledge.enabled,
+      sources: knowledge.sources.map((source) => ({
+        kind: source.kind,
+        value: source.value,
+        title: source.title,
+      })),
+      embedding: knowledge.embedding,
+      retrieval: knowledge.retrieval,
+      internalTool: knowledge.enabled ? KNOWLEDGE_SEARCH_TOOL_NAME : null,
+    },
     access: capsule.config.access,
     storage: {
       driver: capsule.config.storage.driver,

package/src/runtime/deploy-readiness.ts

@@ -24,6 +24,12 @@ export type DeployReadinessContext = {
   userManagedSecrets: string[];
   agentKitManagedSecrets: string[];
   localSecrets: Record<string, DeployReadinessSecretSource>;
+  knowledge: {
+    enabled: boolean;
+    sourceCount: number;
+    embeddingProvider: string;
+    databaseDriver: "none" | "turso";
+  };
 };
 
 export async function loadDeployReadinessContext(
@@ -70,6 +76,12 @@ export async function loadDeployReadinessContext(
     userManagedSecrets: requiredSecrets.filter((name) => !managed.has(name)),
     agentKitManagedSecrets,
     localSecrets,
+    knowledge: {
+      enabled: manifest.knowledge.enabled,
+      sourceCount: manifest.knowledge.sources.length,
+      embeddingProvider: manifest.knowledge.embedding.provider,
+      databaseDriver: manifest.storage.database.driver,
+    },
   };
 }
 

package/src/runtime/dev-server.ts

@@ -13,10 +13,12 @@ import { websiteChannelAdapter } from "./channels/website";
 import { metaWhatsappChannelAdapter } from "./channels/whatsapp-meta";
 import { zapsterWhatsappChannelAdapter } from "./channels/whatsapp-zapster";
 import { runAgentMessage } from "./chat";
+import { isChannelBufferEnabled, renderBufferedChannelMessage, resolveChannelBuffer } from "./channel-buffer";
 import { type LoadedAgentCapsule, loadAgentCapsule } from "./config";
 import { AgentKitError, isAgentKitError } from "./errors";
 import { loadCapsuleEnv } from "./env";
 import { buildInspectState } from "./inspect";
+import { syncConfiguredKnowledgeSources } from "./knowledge/ingest";
 import { runToolFromCwd } from "./tool-runner";
 
 export type AgentDevServerOptions = {
@@ -47,11 +49,28 @@ export type AgentDevServer = {
 const DEFAULT_PORT = 4123;
 const DEFAULT_HOSTNAME = "localhost";
 
+type DevChannelRuntimeState = {
+  dedupeKeys: Set<string>;
+  buffers: Map<string, DevChannelBuffer>;
+};
+
+type DevChannelBuffer = {
+  conversationId: string;
+  messages: Array<{
+    content: string;
+    receivedAt: string;
+  }>;
+  firstReceivedMs: number;
+  lastReceivedMs: number;
+  timer?: ReturnType<typeof setTimeout>;
+};
+
 export async function startAgentDevServer(
   cwd = process.cwd(),
   options: AgentDevServerOptions = {},
 ): Promise<AgentDevServer> {
   const capsule = await loadAgentCapsule(cwd);
+  await syncConfiguredKnowledgeSources(capsule);
   const hostname = options.hostname ?? DEFAULT_HOSTNAME;
   const requestedPort = options.port ?? options.basePort ?? DEFAULT_PORT;
   const autoPort = options.port === undefined;
@@ -124,9 +143,12 @@ async function listenForDevServer(
 }
 
 function createDevHttpServer(capsule: LoadedAgentCapsule): Server {
-  const channelDedupeKeys = new Set<string>();
+  const channelRuntime: DevChannelRuntimeState = {
+    dedupeKeys: new Set<string>(),
+    buffers: new Map<string, DevChannelBuffer>(),
+  };
   return createHttpServer((incoming, outgoing) => {
-    void handleNodeRequest(capsule, incoming, outgoing, channelDedupeKeys);
+    void handleNodeRequest(capsule, incoming, outgoing, channelRuntime);
   });
 }
 
@@ -134,11 +156,11 @@ async function handleNodeRequest(
   capsule: LoadedAgentCapsule,
   incoming: IncomingMessage,
   outgoing: ServerResponse,
-  channelDedupeKeys: Set<string>,
+  channelRuntime: DevChannelRuntimeState,
 ): Promise<void> {
   try {
     const request = nodeRequestToFetchRequest(incoming);
-    const response = await handleDevServerRequest(capsule, request, channelDedupeKeys);
+    const response = await handleDevServerRequest(capsule, request, channelRuntime);
     await writeFetchResponse(outgoing, response);
   } catch (error) {
     await writeFetchResponse(outgoing, jsonError(error, statusForError(error)));
@@ -197,7 +219,7 @@ async function writeFetchResponse(outgoing: ServerResponse, response: Response):
 async function handleDevServerRequest(
   capsule: LoadedAgentCapsule,
   request: Request,
-  channelDedupeKeys: Set<string>,
+  channelRuntime: DevChannelRuntimeState,
 ): Promise<Response> {
   try {
     const url = new URL(request.url);
@@ -257,7 +279,7 @@ async function handleDevServerRequest(
     const channelMatch = route.match(/^\/channels\/([^/]+)\/(website|telegram|whatsapp)\/([^/]+)\/webhook$/);
 
     if (channelMatch) {
-      return await handlePortableChannel(capsule, request, channelDedupeKeys, {
+      return await handlePortableChannel(capsule, request, channelRuntime, {
         name: decodeURIComponent(channelMatch[1]),
         type: channelMatch[2] as ChannelType,
         provider: decodeURIComponent(channelMatch[3]) as ChannelProvider,
@@ -283,7 +305,7 @@ async function handleDevServerRequest(
 async function handlePortableChannel(
   capsule: LoadedAgentCapsule,
   request: Request,
-  dedupeKeys: Set<string>,
+  channelRuntime: DevChannelRuntimeState,
   route: { name: string; type: ChannelType; provider: ChannelProvider },
 ): Promise<Response> {
   const channel = (capsule.config.channels ?? []).find(
@@ -323,21 +345,45 @@ async function handlePortableChannel(
   const deliveries = [];
 
   for (const event of events) {
-    if (dedupeKeys.has(event.dedupeKey)) {
+    if (channelRuntime.dedupeKeys.has(event.dedupeKey)) {
       deliveries.push({ state: "duplicate", dedupeKey: event.dedupeKey });
       continue;
     }
 
-    dedupeKeys.add(event.dedupeKey);
+    channelRuntime.dedupeKeys.add(event.dedupeKey);
 
     if (event.kind !== "message" || !event.message) {
       deliveries.push({ state: "skipped", dedupeKey: event.dedupeKey, unsupportedReason: event.unsupportedReason });
       continue;
     }
 
+    const conversationId = channelConversationId(channel.name, event.externalIdentity.key);
+
+    if (isChannelBufferEnabled(channel)) {
+      const buffer = resolveChannelBuffer(channel);
+      if (buffer.mode !== "debounce") {
+        throw new AgentKitError("runtime_error", "Unexpected channel buffer mode.");
+      }
+
+      bufferDevChannelMessage(capsule, channelRuntime, {
+        bufferKey: `${channel.name}:${event.externalIdentity.key}`,
+        conversationId,
+        content: event.message.content,
+        receivedAt: event.receivedAt,
+        buffer,
+      });
+      deliveries.push({
+        state: "buffered",
+        dedupeKey: event.dedupeKey,
+        conversationId,
+        flushAfterMs: buffer.quietWindowMs,
+      });
+      continue;
+    }
+
     const result = await runAgentMessage(capsule, {
       message: event.message.content,
-      conversationId: channelConversationId(channel.name, event.externalIdentity.key),
+      conversationId,
       signal: request.signal,
     });
     deliveries.push({
@@ -351,6 +397,109 @@ async function handlePortableChannel(
   return jsonResponse({ deliveries });
 }
 
+function bufferDevChannelMessage(
+  capsule: LoadedAgentCapsule,
+  runtime: DevChannelRuntimeState,
+  input: {
+    bufferKey: string;
+    conversationId: string;
+    content: string;
+    receivedAt: string;
+    buffer: {
+      quietWindowMs: number;
+      maxWaitMs: number;
+      maxMessages: number;
+      maxChars: number;
+    };
+  },
+): void {
+  const now = Date.now();
+  const existing = runtime.buffers.get(input.bufferKey);
+  const pending: DevChannelBuffer = existing ?? {
+    conversationId: input.conversationId,
+    messages: [],
+    firstReceivedMs: now,
+    lastReceivedMs: now,
+  };
+
+  if (existing?.timer) {
+    clearTimeout(existing.timer);
+  }
+
+  pending.messages.push({
+    content: input.content,
+    receivedAt: input.receivedAt,
+  });
+  pending.lastReceivedMs = now;
+  runtime.buffers.set(input.bufferKey, pending);
+
+  if (shouldFlushDevChannelBuffer(pending, input.buffer)) {
+    void flushDevChannelBuffer(capsule, runtime, input.bufferKey);
+    return;
+  }
+
+  const elapsedMs = now - pending.firstReceivedMs;
+  const delayMs = Math.max(0, Math.min(input.buffer.quietWindowMs, input.buffer.maxWaitMs - elapsedMs));
+  pending.timer = setTimeout(() => {
+    void flushDevChannelBuffer(capsule, runtime, input.bufferKey);
+  }, delayMs);
+  unrefTimer(pending.timer);
+}
+
+function shouldFlushDevChannelBuffer(
+  pending: DevChannelBuffer,
+  buffer: {
+    maxWaitMs: number;
+    maxMessages: number;
+    maxChars: number;
+  },
+): boolean {
+  const totalChars = pending.messages.reduce((sum, message) => sum + message.content.length, 0);
+  return (
+    pending.messages.length >= buffer.maxMessages ||
+    totalChars >= buffer.maxChars ||
+    Date.now() - pending.firstReceivedMs >= buffer.maxWaitMs
+  );
+}
+
+async function flushDevChannelBuffer(
+  capsule: LoadedAgentCapsule,
+  runtime: DevChannelRuntimeState,
+  bufferKey: string,
+): Promise<void> {
+  const pending = runtime.buffers.get(bufferKey);
+
+  if (!pending) {
+    return;
+  }
+
+  runtime.buffers.delete(bufferKey);
+
+  if (pending.timer) {
+    clearTimeout(pending.timer);
+  }
+
+  const message = renderBufferedChannelMessage(pending.messages);
+
+  try {
+    await runAgentMessage(capsule, {
+      message,
+      conversationId: pending.conversationId,
+      runtime: {
+        invocation: "channel",
+      },
+    });
+  } catch {
+    // Local channel buffering is best-effort; hosted delivery logs own production failures.
+  }
+}
+
+function unrefTimer(timer: ReturnType<typeof setTimeout>): void {
+  if (typeof timer === "object" && timer && "unref" in timer && typeof timer.unref === "function") {
+    timer.unref();
+  }
+}
+
 async function handleLocalFile(capsule: LoadedAgentCapsule, request: Request, rawKey: string): Promise<Response> {
   const key = normalizeFileKey(rawKey);
   const root = resolve(capsule.root, ".agentkit/files");

package/src/runtime/inspect.ts

@@ -4,6 +4,8 @@ import type { AgentChannel, AgentProvider, AgentRuntime, AccessMode } from "../i
 import type { LoadedAgentCapsule } from "./config";
 import { loadAgentCapsule } from "./config";
 import { loadCapsuleEnv } from "./env";
+import { resolveKnowledgeConfig } from "./knowledge/config";
+import { KNOWLEDGE_SEARCH_TOOL_NAME } from "./knowledge/tool";
 
 export type SecretState = "set" | "missing";
 
@@ -14,6 +16,20 @@ export type AgentInspectState = {
   prompt: string;
   tools: string[];
   channels: AgentInspectChannel[];
+  knowledge: {
+    enabled: boolean;
+    sources: string[];
+    embedding: {
+      provider: string;
+      model: string | null;
+      dimensions: number | null;
+    };
+    retrieval: {
+      topK: number;
+      hybrid: boolean;
+    };
+    internalTool: string | null;
+  };
   access: {
     mode: AccessMode;
   };
@@ -56,6 +72,7 @@ export type AgentInspectChannel = {
   type: AgentChannel["type"];
   provider: AgentChannel["provider"];
   secrets: string[];
+  buffer?: AgentChannel["buffer"];
 };
 
 export async function inspectAgentCapsule(
@@ -71,6 +88,7 @@ export function buildInspectState(
   env: Record<string, string | undefined> = process.env,
 ): AgentInspectState {
   const declaredSecrets = new Set(capsule.config.secrets);
+  const knowledge = resolveKnowledgeConfig(capsule.config);
 
   for (const tool of capsule.config.tools ?? []) {
     for (const secret of tool.secrets ?? []) {
@@ -84,6 +102,10 @@ export function buildInspectState(
     }
   }
 
+  if (knowledge.embedding.secret) {
+    declaredSecrets.add(knowledge.embedding.secret);
+  }
+
   const managedSecrets = managedCloudSecrets(capsule);
   const userSecrets = Array.from(declaredSecrets).sort();
   const secrets: Record<string, SecretState> = {};
@@ -105,7 +127,19 @@ export function buildInspectState(
       type: channel.type,
       provider: channel.provider,
       secrets: [...channel.secrets],
+      ...(channel.buffer ? { buffer: channel.buffer } : {}),
     })),
+    knowledge: {
+      enabled: knowledge.enabled,
+      sources: knowledge.sources.map((source) => source.value),
+      embedding: {
+        provider: knowledge.embedding.provider,
+        model: knowledge.embedding.model,
+        dimensions: knowledge.embedding.dimensions,
+      },
+      retrieval: knowledge.retrieval,
+      internalTool: knowledge.enabled ? KNOWLEDGE_SEARCH_TOOL_NAME : null,
+    },
     access: capsule.config.access,
     storage: capsule.storagePath ? toCapsulePath(capsule.root, capsule.storagePath) : null,
     database,