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

package/src/runtime/prompt-context.ts

@@ -0,0 +1,141 @@
+export type RuntimePromptContextOptions = {
+  timeZone?: string | null;
+  env?: Record<string, string | undefined>;
+  now?: Date;
+  clock?: RuntimeClockContext;
+};
+
+export type RuntimePromptContext = {
+  isoTimestamp: string;
+  timeZone: string;
+  localDate: string;
+  localWeekday: string;
+  localDateTime: string;
+};
+
+export type RuntimeClockContext = RuntimePromptContext & {
+  now: Date;
+};
+
+const FALLBACK_TIME_ZONE = "UTC";
+const LOCALE = "en-US";
+
+export function appendRuntimePromptContext(
+  instructions: string,
+  options: RuntimePromptContextOptions = {},
+): string {
+  const context = options.clock ?? buildRuntimePromptContext(options);
+
+  return `${instructions.trimEnd()}
+
+Runtime context:
+- Current timestamp: ${context.isoTimestamp}
+- Time zone: ${context.timeZone}
+- Local date: ${context.localDate}
+- Local weekday: ${context.localWeekday}
+- Local date and time: ${context.localDateTime}
+
+Use this runtime context to interpret relative dates and times such as today, tomorrow, next Friday, and morning/afternoon. If a scheduling request depends on a different user or business time zone, ask for confirmation before booking.`;
+}
+
+export function buildRuntimePromptContext(options: RuntimePromptContextOptions = {}): RuntimePromptContext {
+  const clock = buildRuntimeClockContext(options);
+
+  return {
+    isoTimestamp: clock.isoTimestamp,
+    timeZone: clock.timeZone,
+    localDate: clock.localDate,
+    localWeekday: clock.localWeekday,
+    localDateTime: clock.localDateTime,
+  };
+}
+
+export function buildRuntimeClockContext(options: RuntimePromptContextOptions = {}): RuntimeClockContext {
+  if (options.clock) {
+    return options.clock;
+  }
+
+  const now = new Date((options.now ?? new Date()).getTime());
+
+  if (Number.isNaN(now.getTime())) {
+    throw new Error("runtime prompt context requires a valid Date.");
+  }
+
+  const timeZone = resolveRuntimeTimeZone(options);
+
+  return {
+    now,
+    isoTimestamp: now.toISOString(),
+    timeZone,
+    localDate: formatLocalDate(now, timeZone),
+    localWeekday: formatDateTime(now, timeZone, {
+      weekday: "long",
+    }),
+    localDateTime: formatDateTime(now, timeZone, {
+      weekday: "long",
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+      hour: "numeric",
+      minute: "2-digit",
+      timeZoneName: "short",
+    }),
+  };
+}
+
+export function resolveRuntimeTimeZone(options: RuntimePromptContextOptions = {}): string {
+  if (options.timeZone?.trim()) {
+    return normalizeTimeZone(options.timeZone, "timeZone");
+  }
+
+  const explicitEnvTimeZone = options.env?.AGENTKIT_TIME_ZONE?.trim();
+
+  if (explicitEnvTimeZone) {
+    return normalizeTimeZone(explicitEnvTimeZone, "AGENTKIT_TIME_ZONE");
+  }
+
+  const processTimeZone = options.env?.TZ?.trim();
+
+  if (processTimeZone && isValidTimeZone(processTimeZone)) {
+    return processTimeZone;
+  }
+
+  return normalizeTimeZone(Intl.DateTimeFormat().resolvedOptions().timeZone || FALLBACK_TIME_ZONE, "runtime time zone");
+}
+
+export function isValidTimeZone(value: string): boolean {
+  try {
+    new Intl.DateTimeFormat(LOCALE, { timeZone: value }).format(new Date(0));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeTimeZone(value: string, source: string): string {
+  const timeZone = value.trim();
+
+  if (!isValidTimeZone(timeZone)) {
+    throw new Error(`${source} must be a valid IANA time zone such as "UTC" or "America/New_York".`);
+  }
+
+  return timeZone;
+}
+
+function formatLocalDate(date: Date, timeZone: string): string {
+  const parts = new Intl.DateTimeFormat(LOCALE, {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(date);
+  const byType = Object.fromEntries(parts.map((part) => [part.type, part.value]));
+  return `${byType.year}-${byType.month}-${byType.day}`;
+}
+
+function formatDateTime(date: Date, timeZone: string, options: Intl.DateTimeFormatOptions): string {
+  return new Intl.DateTimeFormat(LOCALE, {
+    ...options,
+    timeZone,
+  }).format(date);
+}

package/src/runtime/runtime-contract.ts

@@ -7,6 +7,10 @@ export type RuntimeContractTarget = {
 
 export type RuntimeContractOptions = {
   expectedAgentName: string;
+  auth?: {
+    chat?: HeadersInit;
+    admin?: HeadersInit;
+  };
   tool: {
     name: string;
     input: unknown;
@@ -20,20 +24,20 @@ export async function assertRuntimeContract(
 ): Promise<void> {
   const baseUrl = target.baseUrl.replace(/\/$/, "");
 
-  const root = await fetch(`${baseUrl}/`);
+  const root = await fetch(`${baseUrl}/`, { headers: options.auth?.chat });
   expect(root.status).toBe(200);
 
   const health = await fetchJson(`${baseUrl}/health`);
   expect(health.status).toBe(200);
   expect(health.body).toMatchObject({ status: "ok" });
 
-  const inspect = await fetchJson(`${baseUrl}/_agentkit`);
+  const inspect = await fetchJson(`${baseUrl}/_agentkit`, { headers: options.auth?.admin });
   expect(inspect.status).toBe(200);
   expect(inspect.body).toMatchObject({ agent: options.expectedAgentName });
 
   const unauthorized = await fetchJson(`${baseUrl}/chat`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers: withHeaders({ "content-type": "application/json" }, options.auth?.chat),
     body: JSON.stringify({ message: { role: "assistant", content: "not allowed" } }),
   });
   expect(unauthorized.status).toBe(400);
@@ -41,7 +45,7 @@ export async function assertRuntimeContract(
 
   const chat = await fetchJson(`${baseUrl}/chat`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers: withHeaders({ "content-type": "application/json" }, options.auth?.chat),
     body: JSON.stringify({ message: { role: "user", content: "my name is Ada" } }),
   });
   expect(chat.status).toBe(200);
@@ -55,7 +59,7 @@ export async function assertRuntimeContract(
 
   const continuedChat = await fetchJson(`${baseUrl}/chat`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers: withHeaders({ "content-type": "application/json" }, options.auth?.chat),
     body: JSON.stringify({ message: "what is my name?", conversationId: chat.body.conversationId }),
   });
   expect(continuedChat.status).toBe(200);
@@ -69,7 +73,7 @@ export async function assertRuntimeContract(
 
   const tool = await fetchJson(`${baseUrl}/tools/${encodeURIComponent(options.tool.name)}`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers: withHeaders({ "content-type": "application/json" }, options.auth?.admin),
     body: JSON.stringify({ input: options.tool.input }),
   });
   expect(tool.status).toBe(200);
@@ -78,7 +82,7 @@ export async function assertRuntimeContract(
     output: options.tool.expectedOutput,
   });
 
-  const conversations = await fetchJson(`${baseUrl}/v1/conversations`);
+  const conversations = await fetchJson(`${baseUrl}/v1/conversations`, { headers: options.auth?.admin });
   expect(conversations.status).toBe(200);
   expect(conversations.body.conversations.length).toBeGreaterThanOrEqual(1);
   expect(conversations.body.conversations.some((conversation: { id: string }) => conversation.id === chat.body.conversationId)).toBe(true);
@@ -91,3 +95,9 @@ async function fetchJson(url: string, init?: RequestInit): Promise<{ status: num
     body: await response.json(),
   };
 }
+
+function withHeaders(required: HeadersInit, extra: HeadersInit | undefined): Headers {
+  const headers = new Headers(extra);
+  new Headers(required).forEach((value, key) => headers.set(key, value));
+  return headers;
+}

package/src/runtime/targets/cloudflare/build.ts

@@ -32,10 +32,12 @@ export type AgentManifest = {
   runtime: "edge";
   target: "cloudflare";
   provider: SharedAgentManifest["provider"];
+  timeZone: SharedAgentManifest["timeZone"];
   prompt: SharedAgentManifest["prompt"];
   secrets: SharedAgentManifest["secrets"];
   tools: SharedAgentManifest["tools"];
   channels: SharedAgentManifest["channels"];
+  transcription: SharedAgentManifest["transcription"];
   knowledge: SharedAgentManifest["knowledge"];
   access: SharedAgentManifest["access"];
   storage: {
@@ -192,10 +194,12 @@ function buildManifest(
     runtime: "edge",
     target: "cloudflare",
     provider: shared.provider,
+    timeZone: shared.timeZone,
     prompt: shared.prompt,
     secrets: shared.secrets,
     tools: shared.tools,
     channels: shared.channels,
+    transcription: shared.transcription,
     knowledge: shared.knowledge,
     access: shared.access,
     storage: {
@@ -538,10 +542,12 @@ function renderCloudflareWorker(input: { manifest: AgentManifest; instructions:
   const instructionsJson = JSON.stringify(input.instructions);
   const configImportPath = JSON.stringify(input.configPath);
   const providerImportPath = JSON.stringify(resolve(moduleDir, "../../../providers/index.ts"));
+  const promptContextImportPath = JSON.stringify(resolve(moduleDir, "../../prompt-context.ts"));
 
   return `import { DurableObject } from "cloudflare:workers";
 import agentConfig from ${configImportPath};
 import { getProviderAdapter } from ${providerImportPath};
+import { appendRuntimePromptContext, buildRuntimeClockContext } from ${promptContextImportPath};
 
 const manifest = ${manifestJson};
 const instructions = ${instructionsJson};
@@ -1123,16 +1129,25 @@ function isRecord(value) {
 
 async function callHostedProvider(env, messages, signal) {
   const adapter = getProviderAdapter(manifest.provider);
+  const clock = buildRuntimeClockContext({
+    timeZone: manifest.timeZone,
+    env,
+  });
   const result = await adapter.run({
     agent: {
       name: manifest.name,
       runtime: manifest.runtime,
       provider: manifest.provider,
     },
-    instructions: withToolVisibilityInstructions(appendHostedKnowledgePromptPolicy(instructions), hostedTools),
+    instructions: appendRuntimePromptContext(
+      withToolVisibilityInstructions(appendHostedKnowledgePromptPolicy(instructions), hostedTools),
+      {
+        clock,
+      },
+    ),
     messages,
     tools: hostedTools,
-    toolRuntime: createHostedProviderToolRuntime(env, signal),
+    toolRuntime: createHostedProviderToolRuntime(env, signal, clock),
     env,
     signal,
   });
@@ -1618,7 +1633,7 @@ function hostedManagedSecrets() {
   return ["TURSO_AUTH_TOKEN", "TURSO_DATABASE_URL"];
 }
 
-function createHostedProviderToolRuntime(env, signal) {
+function createHostedProviderToolRuntime(env, signal, clock) {
   return {
     definitions: hostedTools,
     execute(request) {
@@ -1628,6 +1643,7 @@ function createHostedProviderToolRuntime(env, signal) {
         env,
         signal,
         invocation: "chat",
+        clock,
       });
     },
   };
@@ -1646,6 +1662,10 @@ async function executeHostedTool(request) {
 
   const secrets = resolveToolSecrets(tool, request.env);
   const database = createHostedDatabaseRunner(request.env);
+  const clock = request.clock ?? buildRuntimeClockContext({
+    timeZone: manifest.timeZone,
+    env: request.env,
+  });
   const output = await runToolWithTimeout(
     tool,
     input,
@@ -1653,6 +1673,7 @@ async function executeHostedTool(request) {
       secrets,
       database,
       signal: request.signal,
+      clock,
       runtime: {
         environment: "hosted",
         invocation: request.invocation ?? "tool",
@@ -1717,6 +1738,7 @@ async function runToolWithTimeout(tool, input, context, timeoutMs) {
         secrets: context.secrets,
         signal: controller.signal,
         runtime: context.runtime,
+        clock: context.clock,
         database: context.database,
         db: context.database,
         storage: {

package/src/runtime/targets/container/server.ts

@@ -12,7 +12,7 @@ export async function startContainerRuntime(options: ContainerRuntimeOptions = {
   const capsuleRoot = resolve(options.capsuleRoot ?? process.env.AGENTKIT_CAPSULE_ROOT ?? process.cwd());
   const hostname = options.hostname ?? process.env.HOST ?? "0.0.0.0";
   const port = options.port ?? parsePort(process.env.PORT) ?? 4123;
-  return startAgentDevServer(capsuleRoot, { hostname, port });
+  return startAgentDevServer(capsuleRoot, { hostname, port, access: "enforce" });
 }
 
 function parsePort(value: string | undefined): number | undefined {

package/src/runtime/targets/vps/deploy.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import type { LocalDeployState } from "../../core/deploy-state";
@@ -38,15 +38,19 @@ export async function prepareVpsDeploy(
   const manifest = JSON.parse(await readFile(container.manifestPath, "utf8")) as {
     name: string;
     secrets: string[];
+    access: {
+      mode: "private" | "token" | "public";
+    };
   };
 
   await mkdir(buildDir, { recursive: true });
   const envExample = renderEnvExample(manifest.secrets);
   await writeFile(composePath, renderCompose(manifest.name));
   await writeFile(envExamplePath, envExample);
-  await writeFile(envPath, envExample);
+  await writeFile(envPath, envExample, { mode: 0o600 });
+  await chmod(envPath, 0o600);
   await writeFile(secretsPath, renderSecretsChecklist(manifest.secrets));
-  await writeFile(handoffPath, renderProductionHandoff(options.host, manifest.name));
+  await writeFile(handoffPath, renderProductionHandoff(options.host, manifest.name, manifest.access.mode));
 
   const state: LocalDeployState = {
     deploy_id: `vps_${slugify(manifest.name)}`,
@@ -71,7 +75,8 @@ export async function prepareVpsDeploy(
     },
     created_at: new Date().toISOString(),
   };
-  await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  await chmod(statePath, 0o600);
 
   return {
     target: "vps",
@@ -88,7 +93,7 @@ export async function prepareVpsDeploy(
       `docker compose -f ${composePath} --env-file ${envPath} config`,
       `docker compose -f ${composePath} --env-file ${envPath} up -d --build`,
       `curl -fsS https://${options.host}/health`,
-      `curl -fsS https://${options.host}/_agentkit`,
+      `curl -fsS -H "Authorization: Bearer $AGENTKIT_PRIVATE_TOKEN" https://${options.host}/_agentkit`,
     ],
   };
 }
@@ -145,7 +150,7 @@ ${lines}
 `;
 }
 
-function renderProductionHandoff(host: string, agentName: string): string {
+function renderProductionHandoff(host: string, agentName: string, accessMode: "private" | "token" | "public"): string {
   return `# VPS Production Handoff
 
 ## Deploy
@@ -169,12 +174,14 @@ docker compose -f .agentkit/build/vps/compose.yaml --env-file .agentkit/build/vp
 
 \`\`\`sh
 curl -fsS https://${host}/health
-curl -fsS https://${host}/_agentkit
+curl -fsS -H "Authorization: Bearer $AGENTKIT_PRIVATE_TOKEN" https://${host}/_agentkit
 curl -fsS -X POST https://${host}/chat \\
-  -H 'content-type: application/json' \\
+  -H 'content-type: application/json'${renderChatAuthHeader(accessMode)} \\
   -d '{"message":{"role":"user","content":"hello"}}'
 \`\`\`
 
+Set AGENTKIT_PRIVATE_TOKEN for privileged AgentKit endpoints. Chat access follows access.mode: ${accessMode}.
+
 ## Database
 
 - Default database: SQLite at /data/agentkit.db in the agentkit_data volume.
@@ -195,6 +202,16 @@ docker compose -f .agentkit/build/vps/compose.yaml --env-file .agentkit/build/vp
 `;
 }
 
+function renderChatAuthHeader(accessMode: "private" | "token" | "public"): string {
+  if (accessMode === "public") {
+    return "";
+  }
+
+  const secretName = accessMode === "private" ? "AGENTKIT_PRIVATE_TOKEN" : "AGENTKIT_ACCESS_TOKEN";
+  return ` \\
+  -H "Authorization: Bearer $${secretName}"`;
+}
+
 function slugify(value: string): string {
   const slug = value
     .toLowerCase()

package/src/runtime/tool-runner.ts

@@ -2,12 +2,14 @@ import { loadAgentCapsule } from "./config";
 import { openPreparedCapsuleStore } from "./database";
 import { loadCapsuleEnv } from "./env";
 import { isAgentKitError } from "./errors";
+import { buildRuntimeClockContext } from "./prompt-context";
 import { createToolRuntime, type ToolCallResult } from "./tools";
 
 export type RunToolOptions = {
   name: string;
   input?: unknown;
   signal?: AbortSignal;
+  now?: Date;
 };
 
 export async function runToolFromCwd(cwd: string, options: RunToolOptions): Promise<ToolCallResult> {
@@ -30,6 +32,11 @@ export async function runToolFromCwd(cwd: string, options: RunToolOptions): Prom
     conversationId: conversation.id,
     env,
     signal: options.signal,
+    clock: buildRuntimeClockContext({
+      timeZone: capsule.config.timeZone,
+      env,
+      now: options.now,
+    }),
     runtime: {
       environment: "local",
       invocation: "tool",

package/src/runtime/tools.ts

@@ -2,6 +2,7 @@ import type { AgentTool, JsonSchema, ToolContext, ToolRenderResult, ToolRuntimeC
 import type { SqliteAgentKitStore } from "../storage/sqlite";
 import { createLocalDatabaseRunner } from "./database";
 import { AgentKitError } from "./errors";
+import type { RuntimeClockContext } from "./prompt-context";
 
 export type ToolCallRequest = {
   name: string;
@@ -31,6 +32,7 @@ export type ToolRuntimeOptions = {
   signal?: AbortSignal;
   defaultTimeoutMs?: number;
   runtime: ToolRuntimeContext;
+  clock: RuntimeClockContext;
 };
 
 const DEFAULT_TOOL_TIMEOUT_MS = 30_000;
@@ -89,6 +91,7 @@ async function executeToolCall(
         secrets,
         database,
         runtime: options.runtime,
+        clock: options.clock,
         signal: options.signal,
       },
       tool.timeoutMs ?? options.defaultTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS,
@@ -98,7 +101,7 @@ async function executeToolCall(
       validateSchema(output, tool.outputSchema, `tool "${tool.name}" output`);
     }
 
-    const rendered = renderToolOutput(tool, input, output, options.runtime);
+    const rendered = renderToolOutput(tool, input, output, options.runtime, options.clock);
 
     options.store.completeToolCall({
       toolCallId: toolCall.id,
@@ -135,6 +138,7 @@ function renderToolOutput(
   input: unknown,
   output: unknown,
   runtime: ToolRuntimeContext,
+  clock: RuntimeClockContext,
 ): ToolRenderResult | undefined {
   if (!tool.render) {
     return undefined;
@@ -143,6 +147,7 @@ function renderToolOutput(
   const rendered = tool.render(output, {
     input,
     runtime,
+    clock,
   });
 
   if (typeof rendered === "string") {
@@ -278,7 +283,7 @@ function collectConfiguredSecretValues(tool: AgentTool | undefined, env: Record<
 async function runToolWithTimeout(
   tool: AgentTool,
   input: unknown,
-  context: Pick<ToolContext, "secrets" | "database" | "runtime"> & { signal?: AbortSignal },
+  context: Pick<ToolContext, "secrets" | "database" | "runtime" | "clock"> & { signal?: AbortSignal },
   timeoutMs: number,
 ): Promise<unknown> {
   const controller = new AbortController();
@@ -306,6 +311,7 @@ async function runToolWithTimeout(
         secrets: context.secrets,
         signal: controller.signal,
         runtime: context.runtime,
+        clock: context.clock,
         database: context.database,
         db: context.database,
         storage: {