@andreprado/agentkit 0.1.0-alpha.10

package/src/runtime/dev-server.ts

@@ -0,0 +1,1247 @@
+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";
+import { dirname, join, relative, resolve } from "node:path";
+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 { 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";
+
+export type AgentDevServerOptions = {
+  port?: number;
+  hostname?: string;
+  basePort?: number;
+};
+
+export type AgentDevServer = {
+  capsule: LoadedAgentCapsule;
+  hostname: string;
+  requestedPort: number | null;
+  port: number;
+  portConflict: {
+    port: number;
+    agent?: string;
+  } | null;
+  urls: {
+    chat: string;
+    api: string;
+    inspect: string;
+  };
+  storage: string | null;
+  server: Server;
+  stop(): Promise<void>;
+};
+
+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;
+  const start = await listenForDevServer(capsule, hostname, requestedPort, autoPort);
+
+  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: start.server,
+    async stop() {
+      await closeServer(start.server);
+    },
+  };
+}
+
+async function listenForDevServer(
+  capsule: LoadedAgentCapsule,
+  hostname: string,
+  requestedPort: number,
+  autoPort: boolean,
+): Promise<{ server: Server; actualPort: number; portConflict: AgentDevServer["portConflict"] }> {
+  if (requestedPort === 0) {
+    const server = createDevHttpServer(capsule);
+    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);
+
+    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): Server {
+  const channelRuntime: DevChannelRuntimeState = {
+    dedupeKeys: new Set<string>(),
+    buffers: new Map<string, DevChannelBuffer>(),
+  };
+  const capsuleRoot = capsule.root;
+  return createHttpServer((incoming, outgoing) => {
+    void handleNodeRequest(capsuleRoot, incoming, outgoing, channelRuntime);
+  });
+}
+
+async function handleNodeRequest(
+  capsuleRoot: string,
+  incoming: IncomingMessage,
+  outgoing: ServerResponse,
+  channelRuntime: DevChannelRuntimeState,
+): Promise<void> {
+  try {
+    const capsule = await loadAgentCapsule(capsuleRoot);
+    const request = nodeRequestToFetchRequest(incoming);
+    const response = await handleDevServerRequest(capsule, request, channelRuntime);
+    await writeFetchResponse(outgoing, response);
+  } catch (error) {
+    await writeFetchResponse(outgoing, jsonError(error, statusForError(error)));
+  }
+}
+
+function nodeRequestToFetchRequest(incoming: IncomingMessage): Request {
+  const headers = new Headers();
+
+  for (const [key, value] of Object.entries(incoming.headers)) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        headers.append(key, item);
+      }
+    } else if (value !== undefined) {
+      headers.set(key, value);
+    }
+  }
+
+  const protocol = headers.get("x-forwarded-proto") ?? "http";
+  const host = headers.get("host") ?? `${DEFAULT_HOSTNAME}:${DEFAULT_PORT}`;
+  const url = new URL(incoming.url ?? "/", `${protocol}://${host}`).href;
+  const init: RequestInit & { duplex?: "half" } = {
+    method: incoming.method ?? "GET",
+    headers,
+  };
+
+  if (init.method !== "GET" && init.method !== "HEAD") {
+    init.body = Readable.toWeb(incoming) as unknown as RequestInit["body"];
+    init.duplex = "half";
+  }
+
+  return new Request(url, init);
+}
+
+async function writeFetchResponse(outgoing: ServerResponse, response: Response): Promise<void> {
+  outgoing.statusCode = response.status;
+  response.headers.forEach((value, key) => {
+    outgoing.setHeader(key, value);
+  });
+
+  if (!response.body) {
+    outgoing.end();
+    return;
+  }
+
+  await new Promise<void>((resolvePromise, reject) => {
+    const stream = Readable.fromWeb(response.body as unknown as import("node:stream/web").ReadableStream);
+    stream.once("error", reject);
+    outgoing.once("finish", resolvePromise);
+    outgoing.once("error", reject);
+    stream.pipe(outgoing);
+  });
+}
+
+async function handleDevServerRequest(
+  capsule: LoadedAgentCapsule,
+  request: Request,
+  channelRuntime: DevChannelRuntimeState,
+): Promise<Response> {
+  try {
+    const url = new URL(request.url);
+    const route = normalizePath(url.pathname);
+
+    if (request.method === "GET" && route === "/") {
+      const env = await loadCapsuleEnv(capsule.root);
+      return htmlResponse(renderChatApp(capsule, url.origin, env));
+    }
+
+    if (request.method === "GET" && route === "/_agentkit") {
+      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, conversationId } = readChatRequest(body);
+      const result = await runAgentMessage(capsule, {
+        message,
+        conversationId,
+        signal: request.signal,
+      });
+
+      return jsonResponse({
+        message: result.message,
+        conversationId: result.conversationId,
+        runId: result.runId,
+        userMessageId: result.userMessageId,
+        assistantMessageId: result.assistantMessageId,
+      });
+    }
+
+    const toolMatch = route.match(/^\/tools\/([^/]+)$/);
+
+    if (request.method === "POST" && toolMatch) {
+      const body = await readJsonBody(request);
+      const result = await runToolFromCwd(capsule.root, {
+        name: decodeURIComponent(toolMatch[1]),
+        input: readToolInput(body),
+        signal: request.signal,
+      });
+
+      return jsonResponse(result);
+    }
+
+    const fileMatch = route.match(/^\/files\/(.+)$/);
+
+    if (fileMatch) {
+      return await handleLocalFile(capsule, request, decodeURIComponent(fileMatch[1]));
+    }
+
+    const channelMatch = route.match(/^\/channels\/([^/]+)\/(website|telegram|whatsapp)\/([^/]+)\/webhook$/);
+
+    if (channelMatch) {
+      return await handlePortableChannel(capsule, request, channelRuntime, {
+        name: decodeURIComponent(channelMatch[1]),
+        type: channelMatch[2] as ChannelType,
+        provider: decodeURIComponent(channelMatch[3]) as ChannelProvider,
+      });
+    }
+
+    if (request.method === "GET" && route === "/v1/conversations") {
+      return jsonResponse({ conversations: await listConversations(capsule) });
+    }
+
+    const conversationMatch = route.match(/^\/v1\/conversations\/([^/]+)$/);
+
+    if (request.method === "GET" && conversationMatch) {
+      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));
+  }
+}
+
+async function handlePortableChannel(
+  capsule: LoadedAgentCapsule,
+  request: Request,
+  channelRuntime: DevChannelRuntimeState,
+  route: { name: string; type: ChannelType; provider: ChannelProvider },
+): Promise<Response> {
+  const channel = (capsule.config.channels ?? []).find(
+    (candidate) => candidate.name === route.name && candidate.type === route.type && candidate.provider === route.provider,
+  );
+
+  if (!channel) {
+    throw new AgentKitError("channel_not_found", `Channel "${route.name}" was not found in agentkit.config.ts.`);
+  }
+
+  const adapter = adapterForChannel(route.type, route.provider);
+  const rawBody = request.method === "GET" ? "" : await request.text();
+  const rawEvent: RawWebhookEvent = {
+    type: route.type,
+    provider: route.provider,
+    channelId: channel.name,
+    method: request.method,
+    url: request.url,
+    headers: request.headers,
+    rawBody,
+    receivedAt: new Date().toISOString(),
+  };
+  const secrets = await resolveChannelSecrets(capsule.root, channel);
+  const verification = adapter.verifyWebhook
+    ? await adapter.verifyWebhook({ ...rawEvent, channel, secrets })
+    : { ok: true as const };
+
+  if (!verification.ok) {
+    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 events = await adapter.normalizeInbound(rawEvent);
+  const deliveries = [];
+
+  for (const event of events) {
+    if (channelRuntime.dedupeKeys.has(event.dedupeKey)) {
+      deliveries.push({ state: "duplicate", dedupeKey: event.dedupeKey });
+      continue;
+    }
+
+    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,
+      signal: request.signal,
+    });
+    deliveries.push({
+      state: "sent",
+      dedupeKey: event.dedupeKey,
+      conversationId: result.conversationId,
+      message: result.message,
+    });
+  }
+
+  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");
+  const path = resolve(root, key);
+
+  if (!path.startsWith(`${root}/`) && path !== root) {
+    throw new AgentKitError("file_key_invalid", "File key cannot escape .agentkit/files.");
+  }
+
+  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.`);
+    }
+
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, bytes);
+    return jsonResponse({ key, size: bytes.byteLength });
+  }
+
+  if (request.method === "GET") {
+    try {
+      return new Response(await readFile(path));
+    } catch {
+      throw new AgentKitError("file_not_found", `File "${key}" was not found.`);
+    }
+  }
+
+  if (request.method === "DELETE") {
+    await rm(path, { force: true });
+    return jsonResponse({ key, deleted: true });
+  }
+
+  throw new AgentKitError("method_not_allowed", "Unsupported file method.");
+}
+
+async function listConversations(capsule: LoadedAgentCapsule) {
+  const store = await openCapsuleStore(capsule);
+
+  try {
+    return store.listConversations();
+  } finally {
+    store.close();
+  }
+}
+
+async function getConversation(capsule: LoadedAgentCapsule, conversationId: string): Promise<ConversationRecord> {
+  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;
+  } finally {
+    store.close();
+  }
+}
+
+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") ?? "";
+
+  if (!contentType.toLowerCase().includes("application/json")) {
+    throw new AgentKitError("validation_error", 'POST /v1/chat requires "content-type: application/json".');
+  }
+
+  try {
+    return await request.json();
+  } catch (error) {
+    throw new AgentKitError("validation_error", "Request body must be valid JSON.", { cause: error });
+  }
+}
+
+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 (message.role !== "user") {
+    throw new AgentKitError("validation_error", 'message.role must be "user".');
+  }
+
+  if (typeof message.content !== "string" || message.content.trim().length === 0) {
+    throw new AgentKitError("validation_error", "message.content must be a non-empty string.");
+  }
+
+  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 {
+  if (!isRecord(body)) {
+    throw new AgentKitError("validation_error", 'Expected body shape: {"input":{}}.');
+  }
+
+  return body.input ?? {};
+}
+
+function statusForError(error: unknown): number {
+  if (!isAgentKitError(error)) {
+    return 500;
+  }
+
+  if (
+    error.code === "validation_error" ||
+    error.code === "secret_not_found" ||
+    error.code === "tool_secret_missing" ||
+    error.code === "database_query_invalid"
+  ) {
+    return 400;
+  }
+
+  if (error.code === "constraint_conflict") {
+    return 409;
+  }
+
+  if (
+    error.code === "file_key_invalid" ||
+    error.code === "file_too_large" ||
+    error.code === "channel_payload_invalid" ||
+    error.code === "channel_signature_invalid" ||
+    error.code === "channel_secret_missing"
+  ) {
+    return 400;
+  }
+
+  if (
+    error.code === "conversation_not_found" ||
+    error.code === "not_found" ||
+    error.code === "tool_not_found" ||
+    error.code === "file_not_found" ||
+    error.code === "channel_not_found"
+  ) {
+    return 404;
+  }
+
+  if (error.code === "method_not_allowed") {
+    return 405;
+  }
+
+  if (error.code === "database_unavailable" || error.code === "database_transaction_unsupported") {
+    return 503;
+  }
+
+  if (error.code === "provider_not_supported" || error.code === "provider_model_unsupported") {
+    return 501;
+  }
+
+  return 500;
+}
+
+function jsonError(error: unknown, status: number): Response {
+  const code = isAgentKitError(error) ? error.code : "runtime_error";
+  const message = error instanceof Error ? error.message : String(error);
+
+  return jsonResponse(
+    {
+      error: {
+        code,
+        message,
+      },
+    },
+    { status },
+  );
+}
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  headers.set("content-type", "application/json; charset=utf-8");
+
+  return new Response(JSON.stringify(body, null, 2), {
+    ...init,
+    headers,
+  });
+}
+
+function htmlResponse(body: string): Response {
+  return new Response(body, {
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+    },
+  });
+}
+
+function normalizePath(pathname: string): string {
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    return pathname.slice(0, -1);
+  }
+
+  return pathname;
+}
+
+function normalizeFileKey(rawKey: string): string {
+  const key = rawKey
+    .split("/")
+    .filter((part) => part.length > 0)
+    .join("/");
+
+  if (!key || key.includes("..") || key.startsWith("/") || key.includes("\\")) {
+    throw new AgentKitError("file_key_invalid", "File key must be a relative object key.");
+  }
+
+  return key;
+}
+
+function adapterForChannel(type: ChannelType, provider: ChannelProvider): ChannelAdapter {
+  if (type === "website" && provider === "agentkit") {
+    return websiteChannelAdapter;
+  }
+
+  if (type === "telegram" && provider === "telegram") {
+    return telegramChannelAdapter;
+  }
+
+  if (type === "whatsapp" && provider === "zapster") {
+    return zapsterWhatsappChannelAdapter;
+  }
+
+  if (type === "whatsapp" && provider === "meta") {
+    return metaWhatsappChannelAdapter;
+  }
+
+  throw new AgentKitError("channel_not_found", `No channel adapter for ${type}/${provider}.`);
+}
+
+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] ?? ""]));
+}
+
+function relativePath(root: string, path: string): string {
+  const localPath = relative(root, path);
+  return localPath.length > 0 ? localPath : ".";
+}
+
+function renderChatApp(capsule: LoadedAgentCapsule, baseUrl: string, env: Record<string, string | undefined>): string {
+  const state = buildInspectState(capsule, env);
+  const storage = state.storage ?? "managed";
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(state.agent)} - AgentKit</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --ink: #1c1f22;
+        --muted: #626a73;
+        --line: #d7dde3;
+        --surface: #f7f8f9;
+        --panel: #ffffff;
+        --accent: #116b5f;
+        --accent-ink: #ffffff;
+        --danger: #9f2626;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100svh;
+        color: var(--ink);
+        background: var(--surface);
+        font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      }
+
+      main {
+        display: grid;
+        grid-template-columns: minmax(220px, 320px) minmax(0, 1fr);
+        min-height: 100svh;
+      }
+
+      aside {
+        border-right: 1px solid var(--line);
+        background: #eef2f4;
+        padding: 28px;
+      }
+
+      h1,
+      h2,
+      p {
+        margin: 0;
+      }
+
+      h1 {
+        font-size: 24px;
+        line-height: 1.15;
+        font-weight: 680;
+      }
+
+      .eyebrow {
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+        letter-spacing: 0;
+        text-transform: uppercase;
+        margin-bottom: 10px;
+      }
+
+      .meta {
+        display: grid;
+        gap: 14px;
+        margin-top: 30px;
+      }
+
+      .meta div {
+        display: grid;
+        gap: 4px;
+      }
+
+      .meta span {
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 650;
+      }
+
+      .meta code {
+        overflow-wrap: anywhere;
+        color: var(--ink);
+        font: 13px/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      }
+
+      .workspace {
+        display: grid;
+        grid-template-rows: auto minmax(0, 1fr) auto;
+        min-width: 0;
+        min-height: 100svh;
+      }
+
+      header {
+        border-bottom: 1px solid var(--line);
+        background: var(--panel);
+        padding: 18px 24px;
+      }
+
+      header h2 {
+        font-size: 16px;
+        line-height: 1.3;
+        font-weight: 680;
+      }
+
+      header p {
+        color: var(--muted);
+        margin-top: 2px;
+      }
+
+      #messages {
+        display: flex;
+        flex-direction: column;
+        gap: 14px;
+        overflow: auto;
+        padding: 24px;
+      }
+
+      .message {
+        max-width: 780px;
+        border-left: 3px solid var(--line);
+        padding: 2px 0 2px 14px;
+      }
+
+      .message[data-role="assistant"] {
+        border-left-color: var(--accent);
+      }
+
+      .role {
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+        text-transform: uppercase;
+      }
+
+      .content {
+        margin-top: 4px;
+        white-space: pre-wrap;
+      }
+
+      form {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) auto;
+        gap: 12px;
+        border-top: 1px solid var(--line);
+        background: var(--panel);
+        padding: 16px 24px;
+      }
+
+      textarea {
+        min-height: 48px;
+        max-height: 160px;
+        resize: vertical;
+        border: 1px solid var(--line);
+        border-radius: 6px;
+        padding: 12px 13px;
+        color: var(--ink);
+        background: #fff;
+        font: inherit;
+      }
+
+      textarea:focus {
+        border-color: var(--accent);
+        outline: 3px solid color-mix(in srgb, var(--accent) 18%, transparent);
+      }
+
+      button {
+        align-self: end;
+        min-height: 48px;
+        border: 0;
+        border-radius: 6px;
+        padding: 0 18px;
+        color: var(--accent-ink);
+        background: var(--accent);
+        font: inherit;
+        font-weight: 700;
+        cursor: pointer;
+      }
+
+      button:disabled {
+        cursor: progress;
+        opacity: .64;
+      }
+
+      .error {
+        color: var(--danger);
+      }
+
+      @media (max-width: 760px) {
+        main {
+          grid-template-columns: 1fr;
+        }
+
+        aside {
+          border-right: 0;
+          border-bottom: 1px solid var(--line);
+          padding: 20px;
+        }
+
+        .meta {
+          grid-template-columns: 1fr 1fr;
+          margin-top: 18px;
+        }
+
+        .workspace {
+          min-height: 70svh;
+        }
+
+        form {
+          grid-template-columns: 1fr;
+          padding: 14px;
+        }
+
+        #messages {
+          padding: 18px 14px;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <aside>
+        <p class="eyebrow">AgentKit local</p>
+        <h1>${escapeHtml(state.agent)}</h1>
+        <section class="meta" aria-label="Capsule state">
+          <div>
+            <span>Provider</span>
+            <code>${escapeHtml(state.provider.name)} / ${escapeHtml(state.provider.model)}</code>
+          </div>
+          <div>
+            <span>Runtime</span>
+            <code>${escapeHtml(state.runtime)}</code>
+          </div>
+          <div>
+            <span>Storage</span>
+            <code>${escapeHtml(storage)}</code>
+          </div>
+          <div>
+            <span>Inspect</span>
+            <code>${escapeHtml(new URL("/_agentkit", baseUrl).href)}</code>
+          </div>
+        </section>
+      </aside>
+      <section class="workspace" aria-label="Chat workspace">
+        <header>
+          <h2>Chat</h2>
+          <p>Messages are stored in the capsule SQLite database.</p>
+        </header>
+        <div id="messages" aria-live="polite"></div>
+        <form id="chat-form">
+          <textarea id="message" name="message" placeholder="Send a message to ${escapeHtml(
+            state.agent,
+          )}" required></textarea>
+          <button type="submit">Send</button>
+        </form>
+      </section>
+    </main>
+    <script>
+      const form = document.querySelector("#chat-form");
+      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");
+        wrapper.className = "message " + className;
+        wrapper.dataset.role = role;
+        wrapper.innerHTML = '<div class="role"></div><div class="content"></div>';
+        wrapper.querySelector(".role").textContent = role;
+        wrapper.querySelector(".content").textContent = content;
+        messages.append(wrapper);
+        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();
+        if (!content) return;
+
+        addMessage("user", content);
+        textarea.value = "";
+        button.disabled = true;
+
+        try {
+          const response = await fetch("/v1/chat", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ message: { role: "user", content }, conversationId }),
+          });
+          const data = await response.json();
+
+          if (!response.ok) {
+            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");
+        } finally {
+          button.disabled = false;
+          textarea.focus();
+        }
+      });
+    </script>
+  </body>
+</html>`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function listen(server: Server, hostname: string, port: number): Promise<number> {
+  return new Promise((resolvePromise, reject) => {
+    server.once("error", reject);
+    server.listen(port, hostname, () => {
+      server.off("error", reject);
+      const address = server.address();
+
+      if (address && typeof address === "object") {
+        resolvePromise(address.port);
+        return;
+      }
+
+      reject(new AgentKitError("runtime_error", "Could not determine the AgentKit dev server port."));
+    });
+  });
+}
+
+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) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+
+      resolvePromise();
+    });
+  });
+}
+
+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();
+
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+
+        if (address && typeof address === "object") {
+          resolve(address.port);
+          return;
+        }
+
+        reject(new AgentKitError("runtime_error", "Could not allocate an available local port."));
+      });
+    });
+  });
+}