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

package/src/runtime/database.ts

@@ -1,5 +1,6 @@
-import { readFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { basename, relative, resolve } from "node:path";
 
 import type { DatabaseArgs, DatabaseResult, DatabaseRunner, DatabaseStatement } from "../index";
 import { openCapsuleStore, type SqliteAgentKitStore } from "../storage/sqlite";
@@ -9,6 +10,12 @@ import { AgentKitError } from "./errors";
 export type LocalDatabasePrepareResult = {
   store: SqliteAgentKitStore;
   databasePath: string;
+  migrations: {
+    configured: boolean;
+    path: string | null;
+    applied: string[];
+    skipped: string[];
+  };
   schema: {
     configured: boolean;
     applied: boolean;
@@ -20,10 +27,12 @@ export async function openPreparedCapsuleStore(capsule: LoadedAgentCapsule): Pro
   const store = await openCapsuleStore(capsule);
 
   try {
+    const migrations = await applyCapsuleDatabaseMigrations(capsule, store);
     const schema = await applyCapsuleDatabaseSchema(capsule, store);
     return {
       store,
       databasePath: store.dbPath,
+      migrations,
       schema,
     };
   } catch (error) {
@@ -32,6 +41,84 @@ export async function openPreparedCapsuleStore(capsule: LoadedAgentCapsule): Pro
   }
 }
 
+export async function applyCapsuleDatabaseMigrations(
+  capsule: LoadedAgentCapsule,
+  store: SqliteAgentKitStore,
+): Promise<LocalDatabasePrepareResult["migrations"]> {
+  const database = capsule.config.storage.database;
+
+  if (!database || database.driver !== "turso") {
+    return {
+      configured: false,
+      path: null,
+      applied: [],
+      skipped: [],
+    };
+  }
+
+  const migrationsPath = resolve(capsule.root, database.migrations ?? "migrations");
+  const migrations = await readMigrationFiles(migrationsPath);
+
+  if (migrations.length === 0) {
+    return {
+      configured: false,
+      path: migrationsPath,
+      applied: [],
+      skipped: [],
+    };
+  }
+
+  try {
+    const result = store.applyApplicationMigrations(migrations);
+    return {
+      configured: true,
+      path: migrationsPath,
+      applied: result.applied,
+      skipped: result.skipped,
+    };
+  } catch (error) {
+    if (error instanceof AgentKitError && error.code === "database_schema_error") {
+      throw new AgentKitError(
+        "database_schema_error",
+        [
+          `Could not apply database migrations from ${relative(capsule.root, migrationsPath)}.`,
+          "Migrations must be ordered .sql files and should use safe, forward-only changes.",
+          error.message,
+        ].join(" "),
+        { cause: error },
+      );
+    }
+
+    throw error;
+  }
+}
+
+async function readMigrationFiles(directory: string): Promise<Array<{ id: string; sql: string }>> {
+  let entries: Dirent[];
+
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return [];
+    }
+
+    throw error;
+  }
+
+  const files = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".sql"))
+    .map((entry) => entry.name)
+    .sort();
+
+  return Promise.all(
+    files.map(async (file) => ({
+      id: basename(file, ".sql"),
+      sql: await readFile(resolve(directory, file), "utf8"),
+    })),
+  );
+}
+
 export async function applyCapsuleDatabaseSchema(
   capsule: LoadedAgentCapsule,
   store: SqliteAgentKitStore,
@@ -163,3 +250,7 @@ function validateStatements(statements: DatabaseStatement[]): void {
     validateSql(statement.sql, statement.args ?? []);
   }
 }
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return typeof error === "object" && error !== null && "code" in error;
+}

package/src/runtime/db-commands.ts

@@ -10,6 +10,9 @@ import { AgentKitError } from "./errors";
 export type DbMigrateResult = {
   root: string;
   databasePath: string;
+  migrationsPath: string | null;
+  migrationsApplied: string[];
+  migrationsSkipped: string[];
   schemaPath: string | null;
   schemaApplied: boolean;
 };
@@ -43,6 +46,9 @@ export async function migrateLocalDatabase(cwd = process.cwd()): Promise<DbMigra
     return {
       root: capsule.root,
       databasePath: prepared.databasePath,
+      migrationsPath: prepared.migrations.path,
+      migrationsApplied: prepared.migrations.applied,
+      migrationsSkipped: prepared.migrations.skipped,
       schemaPath: prepared.schema.path,
       schemaApplied: prepared.schema.applied,
     };
@@ -87,6 +93,9 @@ export async function seedLocalDatabase(cwd = process.cwd(), seedFile = "seed.sq
     return {
       root: capsule.root,
       databasePath: prepared.databasePath,
+      migrationsPath: prepared.migrations.path,
+      migrationsApplied: prepared.migrations.applied,
+      migrationsSkipped: prepared.migrations.skipped,
       schemaPath: prepared.schema.path,
       schemaApplied: prepared.schema.applied,
       seedPath,

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,21 +143,26 @@ 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>(),
+  };
+  const capsuleRoot = capsule.root;
   return createHttpServer((incoming, outgoing) => {
-    void handleNodeRequest(capsule, incoming, outgoing, channelDedupeKeys);
+    void handleNodeRequest(capsuleRoot, incoming, outgoing, channelRuntime);
   });
 }
 
 async function handleNodeRequest(
-  capsule: LoadedAgentCapsule,
+  capsuleRoot: string,
   incoming: IncomingMessage,
   outgoing: ServerResponse,
-  channelDedupeKeys: Set<string>,
+  channelRuntime: DevChannelRuntimeState,
 ): Promise<void> {
   try {
+    const capsule = await loadAgentCapsule(capsuleRoot);
     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 +221,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 +281,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,
@@ -274,6 +298,12 @@ async function handleDevServerRequest(
       return jsonResponse(await getConversation(capsule, decodeURIComponent(conversationMatch[1])));
     }
 
+    const conversationTraceMatch = route.match(/^\/v1\/conversations\/([^/]+)\/trace$/);
+
+    if (request.method === "GET" && conversationTraceMatch) {
+      return jsonResponse(await getConversationTrace(capsule, decodeURIComponent(conversationTraceMatch[1])));
+    }
+
     return jsonError(new AgentKitError("not_found", `Route ${request.method} ${route} was not found.`), 404);
   } catch (error) {
     return jsonError(error, statusForError(error));
@@ -283,7 +313,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 +353,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 +405,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");
@@ -421,6 +578,32 @@ async function getConversation(capsule: LoadedAgentCapsule, conversationId: stri
   }
 }
 
+async function getConversationTrace(capsule: LoadedAgentCapsule, conversationId: string) {
+  if (!conversationId) {
+    throw new AgentKitError("validation_error", "Missing conversation id.");
+  }
+
+  const store = await openCapsuleStore(capsule);
+
+  try {
+    const conversation = store.getConversation(conversationId);
+
+    if (!conversation) {
+      throw new AgentKitError("conversation_not_found", `Conversation "${conversationId}" was not found.`);
+    }
+
+    return {
+      ...conversation,
+      runs: store.listRunsForConversation(conversation.id).map((run) => ({
+        ...run,
+        toolCalls: store.listToolCallsForRun(run.id),
+      })),
+    };
+  } finally {
+    store.close();
+  }
+}
+
 async function readJsonBody(request: Request): Promise<unknown> {
   const contentType = request.headers.get("content-type") ?? "";
 
@@ -917,6 +1100,13 @@ function renderChatApp(capsule: LoadedAgentCapsule, baseUrl: string, env: Record
         messages.scrollTop = messages.scrollHeight;
       }
 
+      textarea.addEventListener("keydown", (event) => {
+        if (event.key !== "Enter" || event.shiftKey || event.isComposing) return;
+        event.preventDefault();
+        if (button.disabled) return;
+        form.requestSubmit();
+      });
+
       form.addEventListener("submit", async (event) => {
         event.preventDefault();
         const content = textarea.value.trim();