@andreprado/agentkit 0.1.0-alpha.14 → 0.1.0-alpha.16

package/src/runtime/dev-server.ts

@@ -7,7 +7,7 @@ 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 { telegramChannelAdapter } from "./channels/telegram";
 import { websiteChannelAdapter } from "./channels/website";
 import { metaWhatsappChannelAdapter } from "./channels/whatsapp-meta";
@@ -20,11 +20,13 @@ 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 = {
@@ -49,6 +51,12 @@ export type AgentDevServer = {
 const DEFAULT_PORT = 4123;
 const DEFAULT_HOSTNAME = "localhost";
 
+export type AgentDevServerAccessPolicy = "local" | "enforce";
+
+type DevHttpServerOptions = {
+  access: AgentDevServerAccessPolicy;
+};
+
 type DevChannelRuntimeState = {
   dedupeKeys: Set<string>;
   buffers: Map<string, DevChannelBuffer>;
@@ -74,7 +82,9 @@ export async function startAgentDevServer(
   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);
+  const start = await listenForDevServer(capsule, hostname, requestedPort, autoPort, {
+    access: options.access ?? "local",
+  });
 
   if (start.actualPort === undefined) {
     throw new AgentKitError("runtime_error", "Could not determine the AgentKit dev server port.");
@@ -106,9 +116,10 @@ async function listenForDevServer(
   hostname: string,
   requestedPort: number,
   autoPort: boolean,
+  serverOptions: DevHttpServerOptions,
 ): Promise<{ server: Server; actualPort: number; portConflict: AgentDevServer["portConflict"] }> {
   if (requestedPort === 0) {
-    const server = createDevHttpServer(capsule);
+    const server = createDevHttpServer(capsule, serverOptions);
     const actualPort = await listen(server, hostname, await findAvailablePort());
     return { server, actualPort, portConflict: null };
   }
@@ -117,7 +128,7 @@ async function listenForDevServer(
   const lastPort = autoPort ? requestedPort + 50 : requestedPort;
 
   for (let port = requestedPort; port <= lastPort; port += 1) {
-    const server = createDevHttpServer(capsule);
+    const server = createDevHttpServer(capsule, serverOptions);
 
     try {
       const actualPort = await listen(server, hostname, port);
@@ -142,14 +153,14 @@ async function listenForDevServer(
   );
 }
 
-function createDevHttpServer(capsule: LoadedAgentCapsule): Server {
+function createDevHttpServer(capsule: LoadedAgentCapsule, options: DevHttpServerOptions): 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);
+    void handleNodeRequest(capsuleRoot, incoming, outgoing, channelRuntime, options);
   });
 }
 
@@ -158,11 +169,12 @@ async function handleNodeRequest(
   incoming: IncomingMessage,
   outgoing: ServerResponse,
   channelRuntime: DevChannelRuntimeState,
+  options: DevHttpServerOptions,
 ): Promise<void> {
   try {
     const capsule = await loadAgentCapsule(capsuleRoot);
     const request = nodeRequestToFetchRequest(incoming);
-    const response = await handleDevServerRequest(capsule, request, channelRuntime);
+    const response = await handleDevServerRequest(capsule, request, channelRuntime, options);
     await writeFetchResponse(outgoing, response);
   } catch (error) {
     await writeFetchResponse(outgoing, jsonError(error, statusForError(error)));
@@ -222,27 +234,43 @@ async function handleDevServerRequest(
   capsule: LoadedAgentCapsule,
   request: Request,
   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 auth = await authorizeDevRoute(capsule, request, options, "chat", body);
+      if (auth) {
+        return auth;
+      }
+
       const { message, conversationId } = readChatRequest(body);
       const result = await runAgentMessage(capsule, {
         message,
@@ -262,6 +290,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]),
@@ -275,6 +308,11 @@ 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]));
     }
 
@@ -289,18 +327,33 @@ 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])));
     }
 
@@ -310,6 +363,109 @@ async function handleDevServerRequest(
   }
 }
 
+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,
@@ -360,7 +516,9 @@ async function handlePortableChannel(
 
     channelRuntime.dedupeKeys.add(event.dedupeKey);
 
-    if (event.kind !== "message" || !event.message) {
+    const processedMessage = await processDevChannelMessage(capsule, adapter, channel, event.message, secrets);
+
+    if (event.kind !== "message" || !processedMessage) {
       deliveries.push({ state: "skipped", dedupeKey: event.dedupeKey, unsupportedReason: event.unsupportedReason });
       continue;
     }
@@ -376,7 +534,7 @@ async function handlePortableChannel(
       bufferDevChannelMessage(capsule, channelRuntime, {
         bufferKey: `${channel.name}:${event.externalIdentity.key}`,
         conversationId,
-        content: event.message.content,
+        content: processedMessage.content,
         receivedAt: event.receivedAt,
         buffer,
       });
@@ -390,7 +548,7 @@ async function handlePortableChannel(
     }
 
     const result = await runAgentMessage(capsule, {
-      message: event.message.content,
+      message: processedMessage.content,
       conversationId,
       signal: request.signal,
     });
@@ -405,6 +563,71 @@ async function handlePortableChannel(
   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,
@@ -509,6 +732,10 @@ function unrefTimer(timer: ReturnType<typeof setTimeout>): void {
 }
 
 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);
@@ -519,9 +746,7 @@ 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;
+    const maxUploadBytes = capsule.config.storage.files.maxUploadBytes ?? 10 * 1024 * 1024;
 
     if (bytes.byteLength > maxUploadBytes) {
       throw new AgentKitError("file_too_large", `File exceeds max upload size of ${maxUploadBytes} bytes.`);
@@ -715,6 +940,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"
   ) {

package/src/runtime/env.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { chmod, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import { AgentKitError } from "./errors";
@@ -83,7 +83,7 @@ export async function setCapsuleEnv(root: string, name: string, value: string):
     }
   }
 
-  await writeFile(path, `${nextLines.join("\n").replace(/\n*$/, "")}\n`);
+  await writeSecureDotEnv(path, `${nextLines.join("\n").replace(/\n*$/, "")}\n`);
 }
 
 export async function unsetCapsuleEnv(root: string, name: string): Promise<boolean> {
@@ -103,10 +103,15 @@ export async function unsetCapsuleEnv(root: string, name: string): Promise<boole
     return false;
   }
 
-  await writeFile(path, `${nextLines.join("\n").replace(/\n*$/, "")}\n`);
+  await writeSecureDotEnv(path, `${nextLines.join("\n").replace(/\n*$/, "")}\n`);
   return true;
 }
 
+async function writeSecureDotEnv(path: string, source: string): Promise<void> {
+  await writeFile(path, source, { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
 async function readDotEnvSource(path: string): Promise<string> {
   try {
     return await readFile(path, "utf8");