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

package/src/cli/process.ts

@@ -0,0 +1,31 @@
+import { spawn } from "node:child_process";
+
+export function runInheritedCommand(command: string, args: string[], cwd: string): Promise<number> {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: "inherit",
+    });
+
+    child.once("error", reject);
+    child.once("close", (code) => resolvePromise(code ?? 1));
+  });
+}
+
+export async function waitForShutdown(stop: () => Promise<void>): Promise<void> {
+  await new Promise<void>((resolve) => {
+    let stopped = false;
+
+    const shutdown = () => {
+      if (stopped) {
+        return;
+      }
+
+      stopped = true;
+      void stop().finally(resolve);
+    };
+
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+  });
+}

package/src/cloud/artifact.ts

@@ -1,10 +1,15 @@
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
+import { extname, isAbsolute, relative, resolve } from "node:path";
 
 import type { AgentBuildResult, AgentManifestWithBundle } from "../runtime/targets/cloudflare/build";
 import { AgentKitError } from "../runtime/errors";
 import type { HostedDeployArtifact } from "./contracts";
 
+const HOSTED_KNOWLEDGE_MAX_SOURCE_BYTES = 5 * 1024 * 1024;
+const HOSTED_KNOWLEDGE_MAX_TOTAL_BYTES = 9 * 1024 * 1024;
+const HOSTED_KNOWLEDGE_SUPPORTED_EXTENSIONS = new Set([".md", ".markdown", ".txt", ".csv"]);
+
 export async function createHostedDeployArtifact(build: AgentBuildResult): Promise<HostedDeployArtifact> {
   const [manifestSource, workerSource, wranglerSource] = await Promise.all([
     readFile(build.manifestPath, "utf8"),
@@ -40,9 +45,95 @@ export async function createHostedDeployArtifact(build: AgentBuildResult): Promi
     };
   }
 
+  if (manifest.knowledge.enabled) {
+    artifact.knowledge_sources = await createHostedKnowledgeSources(build.root, manifest);
+  }
+
   return artifact;
 }
 
+async function createHostedKnowledgeSources(
+  root: string,
+  manifest: AgentManifestWithBundle,
+): Promise<NonNullable<HostedDeployArtifact["knowledge_sources"]>> {
+  const sources: NonNullable<HostedDeployArtifact["knowledge_sources"]>["sources"] = [];
+  let totalBytes = 0;
+
+  for (const source of manifest.knowledge.sources) {
+    if (source.kind === "url") {
+      throw new AgentKitError(
+        "artifact_knowledge_source_unsupported",
+        "Hosted deploy can automatically sync local Knowledge files only. URL Knowledge sources require a hosted ingestion connector.",
+      );
+    }
+
+    const absolutePath = resolve(root, source.value);
+    const sourceKey = capsuleRelativePath(root, absolutePath);
+    const extension = extname(sourceKey).toLowerCase();
+
+    if (!HOSTED_KNOWLEDGE_SUPPORTED_EXTENSIONS.has(extension)) {
+      throw new AgentKitError(
+        "artifact_knowledge_source_unsupported",
+        `Knowledge source "${sourceKey}" is not supported for hosted deploy. Use .md, .txt, or .csv.`,
+      );
+    }
+
+    const stats = await stat(absolutePath).catch((error) => {
+      throw new AgentKitError("artifact_knowledge_source_missing", `Knowledge source "${sourceKey}" was not found.`, {
+        cause: error,
+      });
+    });
+
+    if (!stats.isFile()) {
+      throw new AgentKitError("artifact_knowledge_source_invalid", `Knowledge source "${sourceKey}" must be a file.`);
+    }
+
+    if (stats.size > HOSTED_KNOWLEDGE_MAX_SOURCE_BYTES) {
+      throw new AgentKitError(
+        "artifact_knowledge_source_too_large",
+        `Knowledge source "${sourceKey}" is too large for automatic deploy sync. Keep each source under 5MB.`,
+      );
+    }
+
+    totalBytes += stats.size;
+
+    if (totalBytes > HOSTED_KNOWLEDGE_MAX_TOTAL_BYTES) {
+      throw new AgentKitError(
+        "artifact_knowledge_sources_too_large",
+        "Knowledge sources are too large for automatic deploy sync. Keep total packaged Knowledge under 9MB.",
+      );
+    }
+
+    const content = await readFile(absolutePath, "utf8");
+    sources.push({
+      kind: "file",
+      source_key: sourceKey,
+      title: source.title,
+      content,
+      sha256: sha256(content),
+    });
+  }
+
+  return {
+    content_type: "application/json",
+    sources,
+    sha256: sha256(JSON.stringify(sources)),
+  };
+}
+
+function capsuleRelativePath(root: string, absolutePath: string): string {
+  const relativePath = relative(root, absolutePath);
+
+  if (!relativePath || relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new AgentKitError(
+      "artifact_knowledge_source_outside_capsule",
+      "Knowledge source paths must stay inside the Agent Capsule.",
+    );
+  }
+
+  return relativePath.split("\\").join("/");
+}
+
 function sha256(source: string): string {
   return createHash("sha256").update(source).digest("hex");
 }

package/src/cloud/contracts.ts

@@ -16,6 +16,17 @@ export type HostedDeployArtifact = {
     source: string;
     sha256: string;
   };
+  knowledge_sources?: {
+    content_type: "application/json";
+    sources: Array<{
+      kind: "file";
+      source_key: string;
+      title: string | null;
+      content: string;
+      sha256: string;
+    }>;
+    sha256: string;
+  };
 };
 
 export type CreateDeployRequest = {
@@ -37,6 +48,11 @@ export type CreateDeployResponse = {
       mode: string;
       private_token?: string;
     };
+    knowledge?: {
+      enabled: boolean;
+      sources: number;
+      chunks: number;
+    };
   };
 };
 

package/src/create-project.ts

@@ -1,10 +1,10 @@
 import { execFile } from "node:child_process";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 
-import { getTemplate } from "./templates";
+import { getTemplate, type TemplateFile } from "./templates";
 
 const execFileAsync = promisify(execFile);
 const moduleDir = dirname(fileURLToPath(import.meta.url));
@@ -27,9 +27,12 @@ export async function createProject(options: CreateProjectOptions): Promise<Crea
 
   const template = getTemplate(options.template);
   const projectPath = target.path;
-  const files = template.files(target.name, {
-    agentkitDependency: await resolveAgentKitDependency(),
-  });
+  const files = [
+    ...template.files(target.name, {
+      agentkitDependency: await resolveAgentKitDependency(),
+    }),
+    ...(await loadDefaultSkillFiles()),
+  ];
 
   if (target.currentDirectory) {
     await ensureNoFileCollisions(projectPath, files.map((file) => file.path));
@@ -126,6 +129,35 @@ async function resolveAgentKitDependency(): Promise<string> {
   return packageJson.version;
 }
 
+async function loadDefaultSkillFiles(): Promise<TemplateFile[]> {
+  const sourceRoot = join(moduleDir, "templates", "skills");
+  const sourceFiles = await listFiles(sourceRoot);
+
+  return Promise.all(
+    sourceFiles.map(async (sourcePath) => ({
+      path: join("skills", relative(sourceRoot, sourcePath)).replaceAll("\\", "/"),
+      contents: await readFile(sourcePath, "utf8"),
+    })),
+  );
+}
+
+async function listFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const path = join(directory, entry.name);
+
+      if (entry.isDirectory()) {
+        return listFiles(path);
+      }
+
+      return entry.isFile() ? [path] : [];
+    }),
+  );
+
+  return files.flat().sort();
+}
+
 async function directoryExists(path: string): Promise<boolean> {
   try {
     const result = await stat(path);

package/src/index.ts

@@ -17,6 +17,28 @@ export type ChannelLimits = {
   usdPerDay?: number;
 };
 
+export type ChannelBufferMode = "off" | "debounce";
+
+export type ChannelBufferInput = {
+  mode?: ChannelBufferMode;
+  quietWindowMs?: number;
+  maxWaitMs?: number;
+  maxMessages?: number;
+  maxChars?: number;
+};
+
+export type ChannelBufferConfig =
+  | {
+      mode: "off";
+    }
+  | {
+      mode: "debounce";
+      quietWindowMs: number;
+      maxWaitMs: number;
+      maxMessages: number;
+      maxChars: number;
+    };
+
 export type WebsiteChannelAccess = {
   mode: "token";
 };
@@ -26,6 +48,7 @@ export type WebsiteChannelInput = {
   access?: WebsiteChannelAccess;
   secrets?: string[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
 };
 
 export type WebsiteChannelConfig = {
@@ -35,6 +58,7 @@ export type WebsiteChannelConfig = {
   access: WebsiteChannelAccess;
   secrets: string[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
 };
 
 export type TelegramChannelInput = {
@@ -42,6 +66,7 @@ export type TelegramChannelInput = {
   secrets?: string[];
   allowedUpdates?: TelegramAllowedUpdate[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
 };
 
 export type TelegramChannelConfig = {
@@ -51,6 +76,7 @@ export type TelegramChannelConfig = {
   secrets: string[];
   allowedUpdates: TelegramAllowedUpdate[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
 };
 
 export type WhatsappChannelInput = {
@@ -58,6 +84,7 @@ export type WhatsappChannelInput = {
   provider: WhatsappChannelProvider;
   secrets?: string[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
 };
 
 export type WhatsappChannelConfig = {
@@ -66,6 +93,7 @@ export type WhatsappChannelConfig = {
   name: string;
   secrets: string[];
   limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
 };
 
 export type AgentChannel = WebsiteChannelConfig | TelegramChannelConfig | WhatsappChannelConfig;
@@ -90,6 +118,37 @@ export type AgentFilesConfig =
       maxUploadBytes?: number;
     };
 
+export type AgentKnowledgeSource =
+  | string
+  | {
+      path: string;
+      title?: string;
+    }
+  | {
+      url: string;
+      title?: string;
+    };
+
+export type AgentKnowledgeEmbeddingProvider = "none" | "test" | "openai";
+
+export type AgentKnowledgeEmbeddingConfig = {
+  provider?: AgentKnowledgeEmbeddingProvider;
+  model?: string;
+  dimensions?: number;
+  secret?: string;
+};
+
+export type AgentKnowledgeRetrievalConfig = {
+  topK?: number;
+  hybrid?: boolean;
+};
+
+export type AgentKnowledgeConfig = {
+  sources?: AgentKnowledgeSource[];
+  embedding?: AgentKnowledgeEmbeddingConfig;
+  retrieval?: AgentKnowledgeRetrievalConfig;
+};
+
 export type JsonSchema = {
   type: string | string[];
   properties?: Record<string, JsonSchema>;
@@ -157,6 +216,7 @@ export type AgentConfig = {
   secrets: string[];
   tools?: AgentTool[];
   channels?: AgentChannel[];
+  knowledge?: AgentKnowledgeConfig;
   access: {
     mode: AccessMode;
   };
@@ -184,6 +244,7 @@ export function websiteChannel(input: WebsiteChannelInput): WebsiteChannelConfig
     access: input.access ?? { mode: "token" },
     secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"], "website channel"),
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "website channel") } : {}),
   };
 }
 
@@ -198,6 +259,7 @@ export function telegramChannel(input: TelegramChannelInput): TelegramChannelCon
     ),
     allowedUpdates: input.allowedUpdates ?? ["message"],
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "telegram channel") } : {}),
   };
 }
 
@@ -211,6 +273,7 @@ export function whatsappChannel(input: WhatsappChannelInput): WhatsappChannelCon
       `${input.provider} whatsapp channel`,
     ),
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, `${input.provider} whatsapp channel`) } : {}),
   };
 }
 
@@ -236,6 +299,41 @@ function normalizeChannelSecrets(secrets: string[], context: string): string[] {
   return Array.from(uniqueSecrets).sort();
 }
 
+function normalizeChannelBuffer(input: ChannelBufferInput, context: string): ChannelBufferConfig {
+  if (input.mode === "off") {
+    return { mode: "off" };
+  }
+
+  if (input.mode !== undefined && input.mode !== "debounce") {
+    throw new Error(`${context} buffer.mode must be "off" or "debounce".`);
+  }
+
+  const buffer: ChannelBufferConfig = {
+    mode: "debounce",
+    quietWindowMs: input.quietWindowMs ?? 2500,
+    maxWaitMs: input.maxWaitMs ?? 12000,
+    maxMessages: input.maxMessages ?? 20,
+    maxChars: input.maxChars ?? 8000,
+  };
+
+  validatePositiveInteger(buffer.quietWindowMs, `${context} buffer.quietWindowMs`);
+  validatePositiveInteger(buffer.maxWaitMs, `${context} buffer.maxWaitMs`);
+  validatePositiveInteger(buffer.maxMessages, `${context} buffer.maxMessages`);
+  validatePositiveInteger(buffer.maxChars, `${context} buffer.maxChars`);
+
+  if (buffer.maxWaitMs < buffer.quietWindowMs) {
+    throw new Error(`${context} buffer.maxWaitMs must be greater than or equal to buffer.quietWindowMs.`);
+  }
+
+  return buffer;
+}
+
+function validatePositiveInteger(value: number, field: string): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${field} must be a positive integer.`);
+  }
+}
+
 export { loadAgentCapsule, findAgentCapsuleRoot } from "./runtime/config";
 export { runAgentMessage, runAgentMessageFromCwd } from "./runtime/chat";
 export { listConversationsFromCwd, getConversationFromCwd } from "./runtime/conversations";

package/src/runtime/channel-buffer.ts

@@ -0,0 +1,30 @@
+import type { ChannelBufferConfig, ChannelType } from "../index";
+
+export type ChannelBufferCarrier = {
+  type: ChannelType;
+  buffer?: ChannelBufferConfig;
+};
+
+export type ChannelBufferedMessage = {
+  content: string;
+  receivedAt: string;
+};
+
+export function resolveChannelBuffer(channel: ChannelBufferCarrier): ChannelBufferConfig {
+  return channel.buffer ?? { mode: "off" };
+}
+
+export function isChannelBufferEnabled(channel: ChannelBufferCarrier): boolean {
+  return resolveChannelBuffer(channel).mode === "debounce";
+}
+
+export function renderBufferedChannelMessage(messages: ChannelBufferedMessage[]): string {
+  if (messages.length === 1) {
+    return messages[0]?.content ?? "";
+  }
+
+  const lines = messages.map((message, index) => `${index + 1}. ${message.content}`);
+
+  return `The client sent ${messages.length} messages in one burst. Answer once, using the full context below:\n\n${lines.join("\n")}`;
+}
+

package/src/runtime/channels.ts

@@ -8,6 +8,7 @@ export type ChannelDeliveryState =
   | "received"
   | "validated"
   | "duplicate"
+  | "buffered"
   | "queued"
   | "running"
   | "sent"

package/src/runtime/chat.ts

@@ -7,6 +7,9 @@ import { loadAgentCapsule } from "./config";
 import { openPreparedCapsuleStore } from "./database";
 import { loadCapsuleEnv } from "./env";
 import { AgentKitError, isAgentKitError } from "./errors";
+import { syncConfiguredKnowledgeSources } from "./knowledge/ingest";
+import { appendKnowledgePromptPolicy } from "./knowledge/prompt-policy";
+import { createKnowledgeSearchTool } from "./knowledge/tool";
 import { createToolRuntime } from "./tools";
 
 export type RunAgentMessageOptions = {
@@ -37,6 +40,7 @@ export async function runAgentMessage(
 
   const adapter = getProviderAdapter(capsule.config.provider);
   const env = await loadCapsuleEnv(capsule.root);
+  await syncConfiguredKnowledgeSources(capsule);
   const { store } = await openPreparedCapsuleStore(capsule);
   const conversationId = normalizeConversationId(options.conversationId);
   const { conversation, previousMessages } = resolveConversation(store, {
@@ -55,8 +59,9 @@ export async function runAgentMessage(
     provider: capsule.config.provider.name,
     model: capsule.config.provider.model,
   });
+  const runtimeTools = withKnowledgeTools(capsule);
   const toolRuntime = createToolRuntime({
-    tools: capsule.config.tools ?? [],
+    tools: runtimeTools,
     store,
     runId: run.id,
     conversationId: conversation.id,
@@ -78,7 +83,10 @@ export async function runAgentMessage(
         runtime: capsule.config.runtime,
         provider: capsule.config.provider,
       },
-      instructions: withToolVisibilityInstructions(capsule.instructions, capsule.config.tools ?? []),
+      instructions: withToolVisibilityInstructions(
+        appendKnowledgePromptPolicy(capsule.instructions, capsule.config),
+        runtimeTools,
+      ),
       messages,
       tools: toolRuntime.definitions,
       toolRuntime,
@@ -119,6 +127,17 @@ export async function runAgentMessage(
   }
 }
 
+function withKnowledgeTools(capsule: LoadedAgentCapsule): NonNullable<LoadedAgentCapsule["config"]["tools"]> {
+  const tools = [...(capsule.config.tools ?? [])];
+  const knowledgeTool = createKnowledgeSearchTool(capsule);
+
+  if (knowledgeTool) {
+    return [knowledgeTool, ...tools];
+  }
+
+  return tools;
+}
+
 function resolveConversation(
   store: Awaited<ReturnType<typeof openPreparedCapsuleStore>>["store"],
   input: {