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

package/src/runtime/chat.ts

@@ -10,6 +10,7 @@ import { AgentKitError, isAgentKitError } from "./errors";
 import { syncConfiguredKnowledgeSources } from "./knowledge/ingest";
 import { appendKnowledgePromptPolicy } from "./knowledge/prompt-policy";
 import { createKnowledgeSearchTool } from "./knowledge/tool";
+import { appendRuntimePromptContext, buildRuntimeClockContext } from "./prompt-context";
 import { createToolRuntime } from "./tools";
 
 export type RunAgentMessageOptions = {
@@ -17,6 +18,7 @@ export type RunAgentMessageOptions = {
   conversationId?: string;
   signal?: AbortSignal;
   runtime?: Partial<ToolRuntimeContext>;
+  now?: Date;
 };
 
 export type AgentRunResult = ProviderRunResult & PersistedChatRun;
@@ -41,51 +43,64 @@ export async function runAgentMessage(
   const adapter = getProviderAdapter(capsule.config.provider);
   const env = await loadCapsuleEnv(capsule.root);
   await syncConfiguredKnowledgeSources(capsule);
-  const { store } = await openPreparedCapsuleStore(capsule);
   const conversationId = normalizeConversationId(options.conversationId);
-  const { conversation, previousMessages } = resolveConversation(store, {
-    agentName: capsule.config.name,
-    conversationId,
-    firstMessage: content,
-  });
-  const messages: AgentMessage[] = [...previousMessages, { role: "user", content }];
-  const userMessage = store.appendMessage({
-    conversationId: conversation.id,
-    role: "user",
-    content,
-  });
-  const run = store.createRun({
-    conversationId: conversation.id,
-    provider: capsule.config.provider.name,
-    model: capsule.config.provider.model,
-  });
-  const runtimeTools = withKnowledgeTools(capsule);
-  const toolRuntime = createToolRuntime({
-    tools: runtimeTools,
-    store,
-    runId: run.id,
-    conversationId: conversation.id,
-    env,
-    signal: options.signal,
-    runtime: {
-      environment: "local",
-      invocation: "chat",
-      target: "bun",
-      database: "sqlite",
-      ...options.runtime,
-    },
-  });
+  const { store } = await openPreparedCapsuleStore(capsule);
+  let runId: string | null = null;
 
   try {
+    const { conversation, previousMessages } = resolveConversation(store, {
+      agentName: capsule.config.name,
+      conversationId,
+      firstMessage: content,
+    });
+    const messages: AgentMessage[] = [...previousMessages, { role: "user", content }];
+    const userMessage = store.appendMessage({
+      conversationId: conversation.id,
+      role: "user",
+      content,
+    });
+    const run = store.createRun({
+      conversationId: conversation.id,
+      provider: capsule.config.provider.name,
+      model: capsule.config.provider.model,
+    });
+    runId = run.id;
+    const runtimeTools = withKnowledgeTools(capsule);
+    const clock = buildRuntimeClockContext({
+      timeZone: capsule.config.timeZone,
+      env,
+      now: options.now,
+    });
+    const toolRuntime = createToolRuntime({
+      tools: runtimeTools,
+      store,
+      runId: run.id,
+      conversationId: conversation.id,
+      env,
+      signal: options.signal,
+      clock,
+      runtime: {
+        environment: "local",
+        invocation: "chat",
+        target: "bun",
+        database: "sqlite",
+        ...options.runtime,
+      },
+    });
     const result = await adapter.run({
       agent: {
         name: capsule.config.name,
         runtime: capsule.config.runtime,
         provider: capsule.config.provider,
       },
-      instructions: withToolVisibilityInstructions(
-        appendKnowledgePromptPolicy(capsule.instructions, capsule.config),
-        runtimeTools,
+      instructions: appendRuntimePromptContext(
+        withToolVisibilityInstructions(
+          appendKnowledgePromptPolicy(capsule.instructions, capsule.config),
+          runtimeTools,
+        ),
+        {
+          clock,
+        },
       ),
       messages,
       tools: toolRuntime.definitions,
@@ -114,12 +129,14 @@ export async function runAgentMessage(
       assistantMessageId: assistantMessage.id,
     };
   } catch (error) {
-    store.completeRun({
-      runId: run.id,
-      status: "failed",
-      errorCode: isAgentKitError(error) ? error.code : "runtime_error",
-      errorMessage: error instanceof Error ? error.message : String(error),
-    });
+    if (runId) {
+      store.completeRun({
+        runId,
+        status: "failed",
+        errorCode: isAgentKitError(error) ? error.code : "runtime_error",
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+    }
 
     throw error;
   } finally {

package/src/runtime/config.ts

@@ -18,6 +18,7 @@ import type {
   ChannelBufferMode,
 } from "../index";
 import { AgentKitError } from "./errors";
+import { isValidTimeZone } from "./prompt-context";
 
 const CONFIG_FILE = "agentkit.config.ts";
 const AGENT_RUNTIMES = new Set<AgentRuntime>(["local", "edge"]);
@@ -207,8 +208,17 @@ function validateAgentConfig(value: unknown): asserts value is AgentConfig {
     throw invalidConfig('provider.model must be "fake" when provider.name is "test".');
   }
 
+  if (value.timeZone !== undefined) {
+    expectString(value.timeZone, "timeZone");
+
+    if (!isValidTimeZone(value.timeZone)) {
+      throw invalidConfig('timeZone must be a valid IANA time zone such as "UTC" or "America/New_York".');
+    }
+  }
+
   expectString(value.instructions, "instructions");
   expectStringArray(value.secrets, "secrets");
+  validateSecretNames(value.secrets, "secrets");
 
   if (value.tools !== undefined) {
     if (!Array.isArray(value.tools)) {
@@ -636,6 +646,7 @@ function validateTool(value: unknown, index: number): asserts value is AgentTool
 
   if (value.secrets !== undefined) {
     expectStringArray(value.secrets, `tools[${index}].secrets`);
+    validateSecretNames(value.secrets, `tools[${index}].secrets`);
   }
 
   if (value.permissions !== undefined) {

package/src/runtime/core/manifest.ts

@@ -15,6 +15,7 @@ export type SharedAgentManifest = {
   name: string;
   runtime: AgentConfig["runtime"];
   provider: AgentConfig["provider"];
+  timeZone: string | null;
   prompt: string;
   secrets: string[];
   tools: Array<{
@@ -80,9 +81,7 @@ export function buildSharedAgentManifest(
   const files = buildFilesManifest(capsule);
   const knowledge = resolveKnowledgeConfig(capsule.config);
 
-  if (capsule.config.access.mode === "private") {
-    requiredSecrets.add("AGENTKIT_PRIVATE_TOKEN");
-  }
+  requiredSecrets.add("AGENTKIT_PRIVATE_TOKEN");
 
   if (capsule.config.access.mode === "token") {
     requiredSecrets.add("AGENTKIT_ACCESS_TOKEN");
@@ -118,6 +117,7 @@ export function buildSharedAgentManifest(
     name: capsule.config.name,
     runtime: capsule.config.runtime,
     provider: capsule.config.provider,
+    timeZone: capsule.config.timeZone ?? null,
     prompt: toCapsulePath(capsule, capsule.instructionsPath),
     secrets: Array.from(requiredSecrets).sort(),
     tools: (capsule.config.tools ?? []).map((tool) => ({

package/src/runtime/deploy-readiness.ts

@@ -85,8 +85,8 @@ export async function loadDeployReadinessContext(
   };
 }
 
-export function stableCloudProjectId(name: string): string {
-  return `proj_${createHash("sha256").update(name).digest("hex").slice(0, 16)}`;
+export function stableCloudProjectId(name: string, accountId?: string | null): string {
+  return `proj_${createHash("sha256").update(`${accountId ? `account:${accountId}` : "anonymous"}:${name}`).digest("hex").slice(0, 16)}`;
 }
 
 function isAgentKitManagedDeploySecret(
@@ -97,7 +97,7 @@ function isAgentKitManagedDeploySecret(
     return true;
   }
 
-  if (context.accessMode === "private" && name === "AGENTKIT_PRIVATE_TOKEN") {
+  if (name === "AGENTKIT_PRIVATE_TOKEN") {
     return true;
   }
 

package/src/runtime/dev-server.ts

@@ -25,6 +25,7 @@ export type AgentDevServerOptions = {
   port?: number;
   hostname?: string;
   basePort?: number;
+  access?: AgentDevServerAccessPolicy;
 };
 
 export type AgentDevServer = {
@@ -49,6 +50,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 +81,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 +115,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 +127,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 +152,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 +168,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 +233,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 +289,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 +307,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 +326,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 +362,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,
@@ -509,6 +664,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 +678,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 +872,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");