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

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,

package/src/runtime/knowledge/chunk.ts

@@ -0,0 +1,333 @@
+import { basename, extname } from "node:path";
+
+export type KnowledgeChunkMetadata = {
+  sourcePath: string;
+  title: string;
+  section: string | null;
+  locator: string | null;
+};
+
+export type KnowledgeChunk = {
+  ordinal: number;
+  content: string;
+  tokenCount: number;
+  metadata: KnowledgeChunkMetadata;
+};
+
+export type ChunkKnowledgeSourceInput = {
+  sourcePath: string;
+  title?: string | null;
+  content: string;
+};
+
+const DEFAULT_MAX_WORDS = 720;
+const DEFAULT_OVERLAP_WORDS = 80;
+
+export function chunkKnowledgeSource(input: ChunkKnowledgeSourceInput): KnowledgeChunk[] {
+  const extension = extname(input.sourcePath).toLowerCase();
+
+  if (extension === ".csv") {
+    return chunkCsv(input);
+  }
+
+  if (extension === ".md" || extension === ".markdown") {
+    return chunkMarkdown(input);
+  }
+
+  return chunkText(input);
+}
+
+function chunkMarkdown(input: ChunkKnowledgeSourceInput): KnowledgeChunk[] {
+  const title = input.title ?? inferTitle(input.sourcePath, input.content);
+  const sections = markdownSections(input.content, title);
+  const chunks: KnowledgeChunk[] = [];
+
+  for (const section of sections) {
+    const contextualContent = [section.heading, section.body].filter(Boolean).join("\n\n").trim();
+    chunks.push(
+      ...splitContentIntoChunks({
+        sourcePath: input.sourcePath,
+        title,
+        section: section.heading || null,
+        locator: section.heading ? `section:${section.heading}` : null,
+        content: contextualContent,
+        startingOrdinal: chunks.length,
+      }),
+    );
+  }
+
+  return ensureAtLeastOneChunk(chunks, input, title);
+}
+
+function chunkText(input: ChunkKnowledgeSourceInput): KnowledgeChunk[] {
+  const title = input.title ?? inferTitle(input.sourcePath, input.content);
+  const paragraphs = input.content
+    .split(/\n{2,}/)
+    .map((paragraph) => paragraph.trim())
+    .filter(Boolean);
+  const content = paragraphs.length > 0 ? paragraphs.join("\n\n") : input.content.trim();
+
+  return ensureAtLeastOneChunk(
+    splitContentIntoChunks({
+      sourcePath: input.sourcePath,
+      title,
+      section: null,
+      locator: null,
+      content,
+      startingOrdinal: 0,
+    }),
+    input,
+    title,
+  );
+}
+
+function chunkCsv(input: ChunkKnowledgeSourceInput): KnowledgeChunk[] {
+  const title = input.title ?? inferTitle(input.sourcePath, input.content);
+  const rows = parseCsv(input.content);
+
+  if (rows.length === 0) {
+    return ensureAtLeastOneChunk([], input, title);
+  }
+
+  const [headers, ...records] = rows;
+
+  if (headers.length === 0 || records.length === 0) {
+    return chunkText(input);
+  }
+
+  const chunks: KnowledgeChunk[] = [];
+
+  for (const [index, record] of records.entries()) {
+    const content = headers
+      .map((header, columnIndex) => {
+        const name = header.trim() || `column_${columnIndex + 1}`;
+        const value = record[columnIndex]?.trim() ?? "";
+        return `${name}: ${value}`;
+      })
+      .join("\n")
+      .trim();
+
+    if (!content) {
+      continue;
+    }
+
+    chunks.push({
+      ordinal: chunks.length,
+      content,
+      tokenCount: estimateTokenCount(content),
+      metadata: {
+        sourcePath: input.sourcePath,
+        title,
+        section: null,
+        locator: `row:${index + 2}`,
+      },
+    });
+  }
+
+  return ensureAtLeastOneChunk(chunks, input, title);
+}
+
+function markdownSections(content: string, fallbackTitle: string): Array<{ heading: string | null; body: string }> {
+  const sections: Array<{ heading: string | null; body: string[] }> = [];
+  let current: { heading: string | null; body: string[] } = { heading: null, body: [] };
+  const headingStack: string[] = [];
+
+  for (const line of content.split(/\r?\n/)) {
+    const heading = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+
+    if (heading) {
+      if (current.body.join("\n").trim()) {
+        sections.push(current);
+      }
+
+      const level = heading[1].length;
+      headingStack.splice(level - 1);
+      headingStack[level - 1] = heading[2].trim();
+      current = {
+        heading: headingStack.filter(Boolean).join(" > "),
+        body: [],
+      };
+      continue;
+    }
+
+    current.body.push(line);
+  }
+
+  if (current.body.join("\n").trim()) {
+    sections.push(current);
+  }
+
+  if (sections.length === 0) {
+    return [{ heading: fallbackTitle, body: content.trim() }];
+  }
+
+  return sections.map((section) => ({
+    heading: section.heading,
+    body: section.body.join("\n").trim(),
+  }));
+}
+
+function splitContentIntoChunks(input: {
+  sourcePath: string;
+  title: string;
+  section: string | null;
+  locator: string | null;
+  content: string;
+  startingOrdinal: number;
+}): KnowledgeChunk[] {
+  const words = wordsOf(input.content);
+
+  if (words.length <= DEFAULT_MAX_WORDS) {
+    const content = input.content.trim();
+
+    if (!content) {
+      return [];
+    }
+
+    return [
+      {
+        ordinal: input.startingOrdinal,
+        content,
+        tokenCount: estimateTokenCount(content),
+        metadata: {
+          sourcePath: input.sourcePath,
+          title: input.title,
+          section: input.section,
+          locator: input.locator,
+        },
+      },
+    ];
+  }
+
+  const chunks: KnowledgeChunk[] = [];
+  let start = 0;
+
+  while (start < words.length) {
+    const end = Math.min(start + DEFAULT_MAX_WORDS, words.length);
+    const content = words.slice(start, end).join(" ");
+
+    chunks.push({
+      ordinal: input.startingOrdinal + chunks.length,
+      content,
+      tokenCount: estimateTokenCount(content),
+      metadata: {
+        sourcePath: input.sourcePath,
+        title: input.title,
+        section: input.section,
+        locator: input.locator ? `${input.locator}:part:${chunks.length + 1}` : `part:${chunks.length + 1}`,
+      },
+    });
+
+    if (end === words.length) {
+      break;
+    }
+
+    start = Math.max(end - DEFAULT_OVERLAP_WORDS, start + 1);
+  }
+
+  return chunks;
+}
+
+function ensureAtLeastOneChunk(
+  chunks: KnowledgeChunk[],
+  input: ChunkKnowledgeSourceInput,
+  title: string,
+): KnowledgeChunk[] {
+  if (chunks.length > 0) {
+    return chunks.map((chunk, index) => ({ ...chunk, ordinal: index }));
+  }
+
+  const content = input.content.trim();
+
+  if (!content) {
+    return [];
+  }
+
+  return [
+    {
+      ordinal: 0,
+      content,
+      tokenCount: estimateTokenCount(content),
+      metadata: {
+        sourcePath: input.sourcePath,
+        title,
+        section: null,
+        locator: null,
+      },
+    },
+  ];
+}
+
+function parseCsv(content: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = "";
+  let quoted = false;
+
+  for (let index = 0; index < content.length; index += 1) {
+    const char = content[index];
+    const next = content[index + 1];
+
+    if (quoted) {
+      if (char === '"' && next === '"') {
+        field += '"';
+        index += 1;
+        continue;
+      }
+
+      if (char === '"') {
+        quoted = false;
+        continue;
+      }
+
+      field += char;
+      continue;
+    }
+
+    if (char === '"') {
+      quoted = true;
+      continue;
+    }
+
+    if (char === ",") {
+      row.push(field);
+      field = "";
+      continue;
+    }
+
+    if (char === "\n") {
+      row.push(field.replace(/\r$/, ""));
+      rows.push(row);
+      row = [];
+      field = "";
+      continue;
+    }
+
+    field += char;
+  }
+
+  row.push(field.replace(/\r$/, ""));
+  if (row.some((value) => value.length > 0)) {
+    rows.push(row);
+  }
+
+  return rows;
+}
+
+function inferTitle(sourcePath: string, content: string): string {
+  const markdownTitle = content.match(/^#\s+(.+)$/m)?.[1]?.trim();
+
+  if (markdownTitle) {
+    return markdownTitle;
+  }
+
+  return basename(sourcePath).replace(/\.[^.]+$/, "") || sourcePath;
+}
+
+function wordsOf(content: string): string[] {
+  return content.replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+}
+
+export function estimateTokenCount(content: string): number {
+  return Math.max(1, wordsOf(content).length);
+}