@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/runtime/dev-server.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { createServer as createHttpServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { createServer as createNetServer } from "node:net";
@@ -6,27 +7,39 @@ import { Readable } from "node:stream";
 
 import { openCapsuleStore, type ConversationRecord } from "../storage/sqlite";
 import type { AgentChannel, ChannelProvider, ChannelType } from "../index";
-import type { ChannelAdapter, RawWebhookEvent } from "./channels";
+import type { ChannelAdapter, NormalizedChannelMessage, RawWebhookEvent } from "./channels";
+import { discordChannelAdapter } from "./channels/discord";
+import { slackChannelAdapter } from "./channels/slack";
 import { telegramChannelAdapter } from "./channels/telegram";
 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";
+import { resolveTranscriptionConfig, transcribeAudio } from "./transcription";
 
 export type AgentDevServerOptions = {
   port?: number;
   hostname?: string;
+  basePort?: number;
+  access?: AgentDevServerAccessPolicy;
 };
 
 export type AgentDevServer = {
   capsule: LoadedAgentCapsule;
   hostname: string;
+  requestedPort: number | null;
   port: number;
+  portConflict: {
+    port: number;
+    agent?: string;
+  } | null;
   urls: {
     chat: string;
     api: string;
@@ -39,50 +52,133 @@ export type AgentDevServer = {
 
 const DEFAULT_PORT = 4123;
 const DEFAULT_HOSTNAME = "localhost";
+const CHANNEL_DEDUPE_TTL_MS = 6 * 60 * 60 * 1000;
+const CHANNEL_DEDUPE_MAX_KEYS = 10_000;
+
+export type AgentDevServerAccessPolicy = "local" | "enforce";
+
+type DevHttpServerOptions = {
+  access: AgentDevServerAccessPolicy;
+};
+
+type DevChannelRuntimeState = {
+  dedupeKeys: BoundedDedupeCache;
+  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 port = options.port === 0 ? await findAvailablePort() : options.port ?? DEFAULT_PORT;
-  const channelDedupeKeys = new Set<string>();
-  const server = createHttpServer((incoming, outgoing) => {
-    void handleNodeRequest(capsule, incoming, outgoing, channelDedupeKeys);
+  const requestedPort = options.port ?? options.basePort ?? DEFAULT_PORT;
+  const autoPort = options.port === undefined;
+  const start = await listenForDevServer(capsule, hostname, requestedPort, autoPort, {
+    access: options.access ?? "local",
   });
-  const actualPort = await listen(server, hostname, port);
 
-  if (actualPort === undefined) {
+  if (start.actualPort === undefined) {
     throw new AgentKitError("runtime_error", "Could not determine the AgentKit dev server port.");
   }
 
+  const actualPort = start.actualPort;
+
   return {
     capsule,
     hostname,
+    requestedPort: options.port === undefined || options.port === 0 ? null : options.port,
     port: actualPort,
+    portConflict: start.portConflict,
     urls: {
       chat: `http://${hostname}:${actualPort}`,
       api: `http://${hostname}:${actualPort}/v1/chat`,
       inspect: `http://${hostname}:${actualPort}/_agentkit`,
     },
     storage: capsule.storagePath ? relativePath(capsule.root, capsule.storagePath) : null,
-    server,
+    server: start.server,
     async stop() {
-      await closeServer(server);
+      await closeServer(start.server);
     },
   };
 }
 
-async function handleNodeRequest(
+async function listenForDevServer(
   capsule: LoadedAgentCapsule,
+  hostname: string,
+  requestedPort: number,
+  autoPort: boolean,
+  serverOptions: DevHttpServerOptions,
+): Promise<{ server: Server; actualPort: number; portConflict: AgentDevServer["portConflict"] }> {
+  if (requestedPort === 0) {
+    const server = createDevHttpServer(capsule, serverOptions);
+    const actualPort = await listen(server, hostname, await findAvailablePort());
+    return { server, actualPort, portConflict: null };
+  }
+
+  let firstConflict: AgentDevServer["portConflict"] = null;
+  const lastPort = autoPort ? requestedPort + 50 : requestedPort;
+
+  for (let port = requestedPort; port <= lastPort; port += 1) {
+    const server = createDevHttpServer(capsule, serverOptions);
+
+    try {
+      const actualPort = await listen(server, hostname, port);
+      return { server, actualPort, portConflict: port === requestedPort ? null : firstConflict };
+    } catch (error) {
+      await closeServerAfterListenError(server);
+
+      if (!autoPort || !isAddressInUseError(error)) {
+        throw error;
+      }
+
+      firstConflict ??= {
+        port,
+        agent: await detectAgentKitOccupant(hostname, port),
+      };
+    }
+  }
+
+  throw new AgentKitError(
+    "runtime_error",
+    `Could not allocate a local AgentKit dev server port after ${requestedPort}-${lastPort}.`,
+  );
+}
+
+function createDevHttpServer(capsule: LoadedAgentCapsule, options: DevHttpServerOptions): Server {
+  const channelRuntime: DevChannelRuntimeState = {
+    dedupeKeys: new BoundedDedupeCache(CHANNEL_DEDUPE_MAX_KEYS, CHANNEL_DEDUPE_TTL_MS),
+    buffers: new Map<string, DevChannelBuffer>(),
+  };
+  const capsuleRoot = capsule.root;
+  return createHttpServer((incoming, outgoing) => {
+    void handleNodeRequest(capsuleRoot, incoming, outgoing, channelRuntime, options);
+  });
+}
+
+async function handleNodeRequest(
+  capsuleRoot: string,
   incoming: IncomingMessage,
   outgoing: ServerResponse,
-  channelDedupeKeys: Set<string>,
+  channelRuntime: DevChannelRuntimeState,
+  options: DevHttpServerOptions,
 ): 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, options);
     await writeFetchResponse(outgoing, response);
   } catch (error) {
     await writeFetchResponse(outgoing, jsonError(error, statusForError(error)));
@@ -141,31 +237,48 @@ async function writeFetchResponse(outgoing: ServerResponse, response: Response):
 async function handleDevServerRequest(
   capsule: LoadedAgentCapsule,
   request: Request,
-  channelDedupeKeys: Set<string>,
+  channelRuntime: DevChannelRuntimeState,
+  options: DevHttpServerOptions,
 ): Promise<Response> {
   try {
     const url = new URL(request.url);
     const route = normalizePath(url.pathname);
 
+    if (request.method === "GET" && route === "/health") {
+      return jsonResponse({ status: "ok", agent: capsule.config.name });
+    }
+
     if (request.method === "GET" && route === "/") {
+      const auth = await authorizeDevRoute(capsule, request, options, "chat");
+      if (auth) {
+        return auth;
+      }
+
       const env = await loadCapsuleEnv(capsule.root);
       return htmlResponse(renderChatApp(capsule, url.origin, env));
     }
 
     if (request.method === "GET" && route === "/_agentkit") {
+      const auth = await authorizeDevRoute(capsule, request, options, "admin");
+      if (auth) {
+        return auth;
+      }
+
       const env = await loadCapsuleEnv(capsule.root);
       return jsonResponse(buildInspectState(capsule, env));
     }
 
-    if (request.method === "GET" && route === "/health") {
-      return jsonResponse({ status: "ok", agent: capsule.config.name });
-    }
-
     if (request.method === "POST" && (route === "/v1/chat" || route === "/chat")) {
       const body = await readJsonBody(request);
-      const message = readUserMessage(body);
+      const auth = await authorizeDevRoute(capsule, request, options, "chat", body);
+      if (auth) {
+        return auth;
+      }
+
+      const { message, conversationId } = readChatRequest(body);
       const result = await runAgentMessage(capsule, {
         message,
+        conversationId,
         signal: request.signal,
       });
 
@@ -181,6 +294,11 @@ async function handleDevServerRequest(
     const toolMatch = route.match(/^\/tools\/([^/]+)$/);
 
     if (request.method === "POST" && toolMatch) {
+      const auth = await authorizeDevRoute(capsule, request, options, "admin");
+      if (auth) {
+        return auth;
+      }
+
       const body = await readJsonBody(request);
       const result = await runToolFromCwd(capsule.root, {
         name: decodeURIComponent(toolMatch[1]),
@@ -194,13 +312,18 @@ async function handleDevServerRequest(
     const fileMatch = route.match(/^\/files\/(.+)$/);
 
     if (fileMatch) {
+      const auth = await authorizeDevRoute(capsule, request, options, "admin");
+      if (auth) {
+        return auth;
+      }
+
       return await handleLocalFile(capsule, request, decodeURIComponent(fileMatch[1]));
     }
 
-    const channelMatch = route.match(/^\/channels\/([^/]+)\/(website|telegram|whatsapp)\/([^/]+)\/webhook$/);
+    const channelMatch = route.match(/^\/channels\/([^/]+)\/(website|telegram|whatsapp|discord|slack)\/([^/]+)\/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,
@@ -208,25 +331,149 @@ async function handleDevServerRequest(
     }
 
     if (request.method === "GET" && route === "/v1/conversations") {
+      const auth = await authorizeDevRoute(capsule, request, options, "admin");
+      if (auth) {
+        return auth;
+      }
+
       return jsonResponse({ conversations: await listConversations(capsule) });
     }
 
     const conversationMatch = route.match(/^\/v1\/conversations\/([^/]+)$/);
 
     if (request.method === "GET" && conversationMatch) {
+      const auth = await authorizeDevRoute(capsule, request, options, "admin");
+      if (auth) {
+        return auth;
+      }
+
       return jsonResponse(await getConversation(capsule, decodeURIComponent(conversationMatch[1])));
     }
 
+    const conversationTraceMatch = route.match(/^\/v1\/conversations\/([^/]+)\/trace$/);
+
+    if (request.method === "GET" && conversationTraceMatch) {
+      const auth = await authorizeDevRoute(capsule, request, options, "admin");
+      if (auth) {
+        return auth;
+      }
+
+      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));
   }
 }
 
+async function authorizeDevRoute(
+  capsule: LoadedAgentCapsule,
+  request: Request,
+  options: DevHttpServerOptions,
+  kind: "chat" | "admin",
+  body?: unknown,
+): Promise<Response | null> {
+  if (options.access === "local") {
+    return null;
+  }
+
+  const env = await loadCapsuleEnv(capsule.root);
+
+  if (kind === "admin") {
+    return authorizeBearerSecret(request, body, env.AGENTKIT_PRIVATE_TOKEN, {
+      missingCode: "deploy_not_ready",
+      missingMessage: "Privileged AgentKit endpoints require AGENTKIT_PRIVATE_TOKEN to be set.",
+      unauthorizedMessage: "Missing or invalid AgentKit admin token.",
+    });
+  }
+
+  if (capsule.config.access.mode === "public") {
+    return null;
+  }
+
+  if (capsule.config.access.mode === "private") {
+    return authorizeBearerSecret(request, body, env.AGENTKIT_PRIVATE_TOKEN, {
+      missingCode: "deploy_not_ready",
+      missingMessage: "Private deploy requires AGENTKIT_PRIVATE_TOKEN to be set.",
+      unauthorizedMessage: "Missing or invalid deploy access token.",
+    });
+  }
+
+  return authorizeBearerSecret(request, body, env.AGENTKIT_ACCESS_TOKEN, {
+    missingCode: "deploy_not_ready",
+    missingMessage: "Token deploy requires AGENTKIT_ACCESS_TOKEN to be set.",
+    unauthorizedMessage: "Missing or invalid deploy access token.",
+  });
+}
+
+function authorizeBearerSecret(
+  request: Request,
+  body: unknown,
+  secret: string | undefined,
+  messages: { missingCode: string; missingMessage: string; unauthorizedMessage: string },
+): Response | null {
+  if (!secret) {
+    return jsonResponse(
+      {
+        error: {
+          code: messages.missingCode,
+          message: messages.missingMessage,
+        },
+      },
+      { status: 503 },
+    );
+  }
+
+  if (readRequestAccessToken(request, body) !== secret) {
+    return jsonResponse(
+      {
+        error: {
+          code: "unauthorized",
+          message: messages.unauthorizedMessage,
+        },
+      },
+      { status: 401 },
+    );
+  }
+
+  return null;
+}
+
+function readRequestAccessToken(request: Request, body: unknown): string {
+  const authorization = request.headers.get("authorization");
+
+  if (authorization?.startsWith("Bearer ")) {
+    return authorization.slice("Bearer ".length).trim();
+  }
+
+  const header =
+    request.headers.get("x-agentkit-access-token") ??
+    request.headers.get("x-agentkit-deploy-access-token") ??
+    "";
+  const token = header.startsWith("Bearer ") ? header.slice("Bearer ".length) : header;
+  if (token.trim()) {
+    return token.trim();
+  }
+
+  if (body && typeof body === "object") {
+    const record = body as { access_token?: unknown; accessToken?: unknown };
+    const bodyToken =
+      typeof record.access_token === "string"
+        ? record.access_token
+        : typeof record.accessToken === "string"
+          ? record.accessToken
+          : "";
+    return bodyToken.trim();
+  }
+
+  return "";
+}
+
 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(
@@ -258,28 +505,59 @@ async function handlePortableChannel(
     throw new AgentKitError(verification.code, verification.message);
   }
 
-  if (channel.type === "whatsapp" && channel.provider === "meta" && request.method === "GET") {
-    return new Response(new URL(request.url).searchParams.get("hub.challenge") ?? "");
+  const webhookResponse = adapter.getWebhookResponse
+    ? await adapter.getWebhookResponse({ ...rawEvent, channel, secrets })
+    : null;
+
+  if (webhookResponse) {
+    return channelAdapterResponse(webhookResponse);
   }
 
   const events = await adapter.normalizeInbound(rawEvent);
   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);
+
+    const processedMessage = await processDevChannelMessage(capsule, adapter, channel, event.message, secrets);
 
-    if (event.kind !== "message" || !event.message) {
+    if (event.kind !== "message" || !processedMessage) {
       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: processedMessage.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,
+      message: processedMessage.content,
+      conversationId,
       signal: request.signal,
     });
     deliveries.push({
@@ -290,10 +568,186 @@ async function handlePortableChannel(
     });
   }
 
+  if (channel.type === "discord" && channel.provider === "discord") {
+    return jsonResponse(discordLocalInteractionResponse(deliveries));
+  }
+
   return jsonResponse({ deliveries });
 }
 
+async function processDevChannelMessage(
+  capsule: LoadedAgentCapsule,
+  adapter: ChannelAdapter,
+  channel: AgentChannel,
+  message: NormalizedChannelMessage | undefined,
+  secrets: Record<string, string>,
+): Promise<NormalizedChannelMessage | null> {
+  if (!message) {
+    return null;
+  }
+
+  if (message.contentType === "text" && message.content) {
+    return message;
+  }
+
+  if (message.contentType !== "audio" || !message.audio || channel.audio?.mode !== "transcribe") {
+    return null;
+  }
+
+  if (!adapter.downloadMedia) {
+    return null;
+  }
+
+  const env = await loadCapsuleEnv(capsule.root);
+  const transcriptionConfig = resolveTranscriptionConfig(capsule.config.transcription);
+  const secretName = transcriptionConfig.secret;
+  const download = await adapter.downloadMedia({
+    type: channel.type,
+    provider: channel.provider,
+    channelId: channel.name,
+    message,
+    secrets: {
+      ...secrets,
+      ...(secretName ? { [secretName]: env[secretName] ?? "" } : {}),
+      ...(env.AGENTKIT_TELEGRAM_API_BASE_URL ? { AGENTKIT_TELEGRAM_API_BASE_URL: env.AGENTKIT_TELEGRAM_API_BASE_URL } : {}),
+    },
+  });
+
+  if (!download.ok) {
+    return null;
+  }
+
+  const transcription = await transcribeAudio({
+    config: transcriptionConfig,
+    secrets: {
+      ...(secretName ? { [secretName]: env[secretName] ?? "" } : {}),
+    },
+    audio: download.audio,
+    filename: download.filename,
+    ...(download.mimeType ? { mimeType: download.mimeType } : {}),
+    ...(download.durationSeconds !== undefined ? { durationSeconds: download.durationSeconds } : {}),
+  });
+
+  if (!transcription.ok) {
+    return null;
+  }
+
+  return {
+    role: "user",
+    contentType: "text",
+    content: `The user sent an audio message.\n\nTranscript:\n${transcription.text}`,
+    providerMessageId: message.providerMessageId,
+  };
+}
+
+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> {
+  if (capsule.config.storage.files?.driver !== "r2") {
+    throw new AgentKitError("files_not_configured", "File storage is not configured for this Agent Capsule.");
+  }
+
   const key = normalizeFileKey(rawKey);
   const root = resolve(capsule.root, ".agentkit/files");
   const path = resolve(root, key);
@@ -303,14 +757,8 @@ async function handleLocalFile(capsule: LoadedAgentCapsule, request: Request, ra
   }
 
   if (request.method === "PUT") {
-    const bytes = new Uint8Array(await request.arrayBuffer());
-    const maxUploadBytes = capsule.config.storage.files?.driver === "r2"
-      ? capsule.config.storage.files.maxUploadBytes ?? 10 * 1024 * 1024
-      : 10 * 1024 * 1024;
-
-    if (bytes.byteLength > maxUploadBytes) {
-      throw new AgentKitError("file_too_large", `File exceeds max upload size of ${maxUploadBytes} bytes.`);
-    }
+    const maxUploadBytes = capsule.config.storage.files.maxUploadBytes ?? 10 * 1024 * 1024;
+    const bytes = await readRequestBytesWithLimit(request, maxUploadBytes);
 
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, bytes);
@@ -333,6 +781,102 @@ async function handleLocalFile(capsule: LoadedAgentCapsule, request: Request, ra
   throw new AgentKitError("method_not_allowed", "Unsupported file method.");
 }
 
+export class BoundedDedupeCache {
+  private readonly entries = new Map<string, number>();
+
+  constructor(
+    private readonly maxKeys: number,
+    private readonly ttlMs: number,
+  ) {}
+
+  has(key: string): boolean {
+    this.pruneExpired();
+    return this.entries.has(key);
+  }
+
+  add(key: string): void {
+    this.pruneExpired();
+    this.entries.set(key, Date.now());
+    this.pruneOverflow();
+  }
+
+  get size(): number {
+    this.pruneExpired();
+    return this.entries.size;
+  }
+
+  private pruneExpired(): void {
+    const cutoff = Date.now() - this.ttlMs;
+
+    for (const [key, timestamp] of this.entries) {
+      if (timestamp >= cutoff) {
+        continue;
+      }
+
+      this.entries.delete(key);
+    }
+  }
+
+  private pruneOverflow(): void {
+    while (this.entries.size > this.maxKeys) {
+      const oldest = this.entries.keys().next().value;
+
+      if (typeof oldest !== "string") {
+        return;
+      }
+
+      this.entries.delete(oldest);
+    }
+  }
+}
+
+async function readRequestBytesWithLimit(request: Request, maxBytes: number): Promise<Uint8Array> {
+  const contentLength = request.headers.get("content-length");
+
+  if (contentLength) {
+    const declaredBytes = Number(contentLength);
+
+    if (Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+      throw new AgentKitError("file_too_large", `File exceeds max upload size of ${maxBytes} bytes.`);
+    }
+  }
+
+  if (!request.body) {
+    return new Uint8Array();
+  }
+
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+
+    if (done) {
+      break;
+    }
+
+    total += value.byteLength;
+
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => undefined);
+      throw new AgentKitError("file_too_large", `File exceeds max upload size of ${maxBytes} bytes.`);
+    }
+
+    chunks.push(value);
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return bytes;
+}
+
 async function listConversations(capsule: LoadedAgentCapsule) {
   const store = await openCapsuleStore(capsule);
 
@@ -363,6 +907,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") ?? "";
 
@@ -377,20 +947,61 @@ async function readJsonBody(request: Request): Promise<unknown> {
   }
 }
 
-function readUserMessage(body: unknown): string {
-  if (!isRecord(body) || !isRecord(body.message)) {
+function readChatRequest(body: unknown): { message: string; conversationId?: string } {
+  if (!isRecord(body)) {
+    throw new AgentKitError(
+      "validation_error",
+      'Expected body shape: {"message":{"role":"user","content":"hello"},"conversationId":"optional-id"}.',
+    );
+  }
+
+  const message = readUserMessage(body.message);
+  const conversationId = readOptionalConversationId(body.conversationId);
+
+  return { message, conversationId };
+}
+
+function readUserMessage(message: unknown): string {
+  if (typeof message === "string") {
+    const content = message.trim();
+
+    if (!content) {
+      throw new AgentKitError("validation_error", "message must be a non-empty string.");
+    }
+
+    return content;
+  }
+
+  if (!isRecord(message)) {
     throw new AgentKitError("validation_error", 'Expected body shape: {"message":{"role":"user","content":"hello"}}.');
   }
 
-  if (body.message.role !== "user") {
+  if (message.role !== "user") {
     throw new AgentKitError("validation_error", 'message.role must be "user".');
   }
 
-  if (typeof body.message.content !== "string" || body.message.content.trim().length === 0) {
+  if (typeof message.content !== "string" || message.content.trim().length === 0) {
     throw new AgentKitError("validation_error", "message.content must be a non-empty string.");
   }
 
-  return body.message.content;
+  return message.content.trim();
+}
+
+function readOptionalConversationId(value: unknown): string | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new AgentKitError("validation_error", "conversationId must be a non-empty string when provided.");
+  }
+
+  return value.trim();
+}
+
+function channelConversationId(channelName: string, externalIdentityKey: string): string {
+  const hash = createHash("sha256").update(`${channelName}:${externalIdentityKey}`).digest("hex").slice(0, 32);
+  return `chn_${hash}`;
 }
 
 function readToolInput(body: unknown): unknown {
@@ -433,6 +1044,7 @@ function statusForError(error: unknown): number {
     error.code === "conversation_not_found" ||
     error.code === "not_found" ||
     error.code === "tool_not_found" ||
+    error.code === "files_not_configured" ||
     error.code === "file_not_found" ||
     error.code === "channel_not_found"
   ) {
@@ -525,9 +1137,69 @@ function adapterForChannel(type: ChannelType, provider: ChannelProvider): Channe
     return metaWhatsappChannelAdapter;
   }
 
+  if (type === "discord" && provider === "discord") {
+    return discordChannelAdapter;
+  }
+
+  if (type === "slack" && provider === "slack") {
+    return slackChannelAdapter;
+  }
+
   throw new AgentKitError("channel_not_found", `No channel adapter for ${type}/${provider}.`);
 }
 
+function channelAdapterResponse(response: {
+  status?: number;
+  headers?: Record<string, string>;
+  body: string | Record<string, unknown>;
+}): Response {
+  if (typeof response.body === "string") {
+    return new Response(response.body, {
+      status: response.status ?? 200,
+      headers: response.headers,
+    });
+  }
+
+  return jsonResponse(response.body, {
+    status: response.status ?? 200,
+    headers: response.headers,
+  });
+}
+
+function discordLocalInteractionResponse(
+  deliveries: Array<{
+    state: string;
+    message?: {
+      content?: string;
+    };
+  }>,
+): Record<string, unknown> {
+  const sent = deliveries.find((delivery) => delivery.state === "sent" && delivery.message?.content);
+
+  if (sent?.message?.content) {
+    return {
+      type: 4,
+      data: {
+        content: sent.message.content,
+        allowed_mentions: {
+          parse: [],
+        },
+      },
+    };
+  }
+
+  return {
+    type: 4,
+    data: {
+      content: "This Discord interaction was received but could not be processed.",
+      flags: 64,
+      allowed_mentions: {
+        parse: [],
+      },
+    },
+  };
+}
+
 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] ?? ""]));
@@ -805,6 +1477,7 @@ function renderChatApp(capsule: LoadedAgentCapsule, baseUrl: string, env: Record
       const textarea = document.querySelector("#message");
       const messages = document.querySelector("#messages");
       const button = form.querySelector("button");
+      let conversationId = null;
 
       function addMessage(role, content, className = "") {
         const wrapper = document.createElement("article");
@@ -817,6 +1490,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();
@@ -830,7 +1510,7 @@ function renderChatApp(capsule: LoadedAgentCapsule, baseUrl: string, env: Record
           const response = await fetch("/v1/chat", {
             method: "POST",
             headers: { "content-type": "application/json" },
-            body: JSON.stringify({ message: { role: "user", content } }),
+            body: JSON.stringify({ message: { role: "user", content }, conversationId }),
           });
           const data = await response.json();
 
@@ -838,6 +1518,7 @@ function renderChatApp(capsule: LoadedAgentCapsule, baseUrl: string, env: Record
             throw new Error(data.error?.message || "Chat request failed.");
           }
 
+          conversationId = data.conversationId || conversationId;
           addMessage(data.message.role, data.message.content);
         } catch (error) {
           addMessage("error", error instanceof Error ? error.message : String(error), "error");
@@ -881,6 +1562,19 @@ function listen(server: Server, hostname: string, port: number): Promise<number>
   });
 }
 
+async function closeServerAfterListenError(server: Server): Promise<void> {
+  if (!server.listening) {
+    try {
+      server.close();
+    } catch {
+      // The server never reached the listening state.
+    }
+    return;
+  }
+
+  await closeServer(server);
+}
+
 function closeServer(server: Server): Promise<void> {
   return new Promise((resolvePromise, reject) => {
     server.close((error) => {
@@ -894,6 +1588,30 @@ function closeServer(server: Server): Promise<void> {
   });
 }
 
+function isAddressInUseError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "EADDRINUSE";
+}
+
+async function detectAgentKitOccupant(hostname: string, port: number): Promise<string | undefined> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 300);
+
+  try {
+    const response = await fetch(`http://${hostname}:${port}/_agentkit`, { signal: controller.signal });
+    const payload = await response.json().catch(() => null);
+
+    if (payload && typeof payload === "object" && "agent" in payload && typeof payload.agent === "string") {
+      return payload.agent;
+    }
+  } catch {
+    return undefined;
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  return undefined;
+}
+
 function findAvailablePort(): Promise<number> {
   return new Promise((resolve, reject) => {
     const server = createNetServer();