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

package/src/cli/deploy-readiness.ts

@@ -1,15 +1,15 @@
 import { findAgentCapsuleRoot, loadAgentCapsule } from "../runtime/config";
-import { readLocalDeployStateIfExists } from "../runtime/core/deploy-state";
-import { loadDeployReadinessContext, stableCloudProjectId, type DeployReadinessContext } from "../runtime/deploy-readiness";
+import { loadDeployReadinessContext, type DeployReadinessContext } from "../runtime/deploy-readiness";
 import { loadCapsuleEnv } from "../runtime/env";
 import { isAgentKitError } from "../runtime/errors";
 import {
   cloudApiRequest,
   formatCloudAuthSource,
-  readCloudAuth,
+  readCloudAuthForApiUrl,
   type CloudCapabilitiesResponse,
   type CloudLimitsResponse,
   type CloudMeResponse,
+  type CloudProjectResolveResponse,
   type CloudSecretsResponse,
 } from "./cloud-client";
 
@@ -34,7 +34,7 @@ export async function checkDeployReadiness(options: {
   requireLogin: boolean;
 }): Promise<DeployReadinessReport> {
   const context = await loadDeployReadinessContext(process.cwd(), process.env);
-  const auth = await readCloudAuth();
+  const auth = options.requireLogin ? await readCloudAuthForApiUrl(options.apiUrl) : null;
   const checks: DeployReadinessCheck[] = [];
   let cloudAuthUsable = false;
 
@@ -82,6 +82,19 @@ export async function checkDeployReadiness(options: {
     }
   }
 
+  if (cloudAuthUsable) {
+    try {
+      context.projectId = await resolveCloudProjectId(options.apiUrl, context.projectName);
+    } catch (error) {
+      checks.push({
+        status: "fail",
+        title: "Project identity",
+        message: `Could not resolve the account-scoped AgentKit Cloud project. ${formatReadinessError(error)}`,
+      });
+      cloudAuthUsable = false;
+    }
+  }
+
   if (cloudAuthUsable) {
     try {
       const payload = (await cloudApiRequest(options.apiUrl, "/v1/me/capabilities", {
@@ -315,16 +328,24 @@ export function formatReadinessError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-export async function resolveProjectIdForSecretCommand(cwd: string): Promise<string> {
-  const state = await readLocalDeployStateIfExists(cwd);
+export async function resolveProjectIdForSecretCommand(cwd: string, apiUrl: string): Promise<string> {
+  const root = await findAgentCapsuleRoot(cwd);
+  const capsule = await loadAgentCapsule(root);
+  return resolveCloudProjectId(apiUrl, capsule.config.name);
+}
 
-  if (state?.project_id) {
-    return state.project_id;
+async function resolveCloudProjectId(apiUrl: string, projectName: string): Promise<string> {
+  const payload = (await cloudApiRequest(apiUrl, "/v1/projects/resolve", {
+    method: "POST",
+    body: JSON.stringify({ project_name: projectName }),
+  })) as CloudProjectResolveResponse;
+  const projectId = payload.project?.id;
+
+  if (!projectId) {
+    throw new Error("AgentKit Cloud did not return a project id.");
   }
 
-  const root = await findAgentCapsuleRoot(cwd);
-  const capsule = await loadAgentCapsule(root);
-  return stableCloudProjectId(capsule.config.name);
+  return projectId;
 }
 
 function secretSetCommand(secret: string, source: DeployReadinessContext["localSecrets"][string] | undefined): string {

package/src/cli/index.ts

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 
 import { createProject } from "../create-project";
@@ -38,6 +38,7 @@ import {
   clearCloudAuth,
   cloudApiRequest,
   readCloudAuth,
+  readCloudAuthForApiUrl,
   readCloudError,
   resolveCloudApiUrl,
   verifyCloudLogin,
@@ -607,10 +608,10 @@ async function main() {
     }
 
     const apiUrl = await resolveCloudApiUrl(args.flags.api);
-    const auth = await readCloudAuth();
+    const auth = anonymous ? null : await readCloudAuthForApiUrl(apiUrl);
     const deploy = await deployBuildToAgentKitCloud(result, {
       apiUrl,
-      apiToken: auth?.token,
+      apiToken: anonymous ? null : auth?.token,
       anonymous: anonymous || !auth?.token,
     });
     const statePath = await writeLocalDeployState(result.root, deploy);
@@ -659,8 +660,8 @@ async function main() {
 
   if (args.command === "secret") {
     const [subcommand, name, ...valueParts] = args.positional;
-    const projectId = await resolveProjectIdForSecretCommand(process.cwd());
     const apiUrl = await resolveCloudApiUrl(args.flags.api);
+    const projectId = await resolveProjectIdForSecretCommand(process.cwd(), apiUrl);
 
     if (subcommand === "list") {
       const payload = await cloudApiRequest(apiUrl, `/v1/projects/${encodeURIComponent(projectId)}/secrets`, {
@@ -949,9 +950,12 @@ async function ensureDeployChatAccessToken(options: {
         `/v1/deploys/${encodeURIComponent(options.deployId)}/access-tokens`,
         { method: "GET" },
       )) as DeployAccessTokenListResponse;
-      const stillExists = (listed.access_tokens ?? []).some((token) => token.id === existing.id);
+      const stillUsable = (listed.access_tokens ?? []).some(
+        (token) => token.id === existing.id && deployAccessTokenMetadataIsUsable(token),
+      );
 
-      if (stillExists) {
+      if (stillUsable) {
+        await chmod(path, 0o600);
         return { status: "ready", path, tokenId: existing.id, created: false };
       }
     }
@@ -977,6 +981,15 @@ async function ensureDeployChatAccessToken(options: {
   }
 }
 
+function deployAccessTokenMetadataIsUsable(token: { expires_at?: string }): boolean {
+  if (!token.expires_at) {
+    return true;
+  }
+
+  const expiresAtMs = Date.parse(token.expires_at);
+  return Number.isFinite(expiresAtMs) && expiresAtMs > Date.now();
+}
+
 async function readDeployAccessTokenFile(path: string): Promise<{ id?: string; deploy_id?: string } | null> {
   try {
     const parsed = JSON.parse(await readFile(path, "utf8")) as DeployAccessTokenCreateResponse;
@@ -989,6 +1002,7 @@ async function readDeployAccessTokenFile(path: string): Promise<{ id?: string; d
 async function writeSecretJson(path: string, value: unknown): Promise<void> {
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  await chmod(path, 0o600);
 }
 
 async function requireLocalDeployState(): Promise<LocalDeployState> {

package/src/cloud/client.ts

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { chmod, mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import type { AgentBuildResult } from "../runtime/targets/cloudflare/build";
@@ -15,7 +15,7 @@ export async function deployBuildToAgentKitCloud(
   const headers = new Headers({
     "Content-Type": "application/json",
   });
-  const apiToken = options.apiToken ?? process.env.AGENTKIT_CLOUD_API_TOKEN;
+  const apiToken = options.anonymous ? undefined : options.apiToken ?? process.env.AGENTKIT_CLOUD_API_TOKEN;
 
   if (apiToken) {
     headers.set("Authorization", `Bearer ${apiToken}`);
@@ -70,7 +70,8 @@ export async function writeLocalDeployState(root: string, deploy: CreateDeployRe
   };
 
   await mkdir(join(root, ".agentkit"), { recursive: true });
-  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 statePath;
 }
 

package/src/cloud/contracts.ts

@@ -58,6 +58,6 @@ export type CreateDeployResponse = {
 
 export type AgentKitCloudDeployOptions = {
   apiUrl: string;
-  apiToken?: string;
+  apiToken?: string | null;
   anonymous?: boolean;
 };

package/src/create-project.ts

@@ -114,7 +114,7 @@ async function resolveAgentKitDependency(): Promise<string> {
 
   const packageRoot = resolve(moduleDir, "..");
 
-  if (await directoryExists(resolve(packageRoot, "../..", ".git"))) {
+  if (await pathExists(resolve(packageRoot, "../..", ".git"))) {
     return `file:${packageRoot}`;
   }
 

package/src/index.ts

@@ -6,6 +6,8 @@ export type ChannelType = "website" | "telegram" | "whatsapp";
 export type ChannelProvider = "agentkit" | "telegram" | "zapster" | "meta";
 export type WhatsappChannelProvider = "zapster" | "meta";
 export type TelegramAllowedUpdate = "message";
+export type ChannelAudioMode = "off" | "reject" | "transcribe";
+export type TranscriptionProviderName = "test" | "openai" | "groq";
 
 export type AgentProvider = {
   name: AgentProviderName;
@@ -39,6 +41,45 @@ export type ChannelBufferConfig =
       maxChars: number;
     };
 
+export type ChannelAudioInput = {
+  mode?: ChannelAudioMode;
+  fallbackMessage?: string;
+  maxDurationSeconds?: number;
+  maxBytes?: number;
+};
+
+export type ChannelAudioConfig =
+  | {
+      mode: "off";
+    }
+  | {
+      mode: "reject";
+      fallbackMessage: string;
+      maxDurationSeconds?: number;
+      maxBytes?: number;
+    }
+  | {
+      mode: "transcribe";
+      fallbackMessage: string;
+      maxDurationSeconds?: number;
+      maxBytes?: number;
+    };
+
+export type AgentTranscriptionLimits = {
+  maxDurationSeconds?: number;
+  maxBytes?: number;
+};
+
+export type AgentTranscriptionConfig = {
+  provider: TranscriptionProviderName;
+  model: string;
+  secret?: string;
+  language?: string;
+  prompt?: string;
+  limits?: AgentTranscriptionLimits;
+  rawAudioTtlSeconds?: number;
+};
+
 export type WebsiteChannelAccess = {
   mode: "token";
 };
@@ -49,6 +90,7 @@ export type WebsiteChannelInput = {
   secrets?: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
+  audio?: ChannelAudioInput;
 };
 
 export type WebsiteChannelConfig = {
@@ -59,6 +101,7 @@ export type WebsiteChannelConfig = {
   secrets: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
+  audio?: ChannelAudioConfig;
 };
 
 export type TelegramChannelInput = {
@@ -67,6 +110,7 @@ export type TelegramChannelInput = {
   allowedUpdates?: TelegramAllowedUpdate[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
+  audio?: ChannelAudioInput;
 };
 
 export type TelegramChannelConfig = {
@@ -77,6 +121,7 @@ export type TelegramChannelConfig = {
   allowedUpdates: TelegramAllowedUpdate[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
+  audio?: ChannelAudioConfig;
 };
 
 export type WhatsappChannelInput = {
@@ -85,6 +130,7 @@ export type WhatsappChannelInput = {
   secrets?: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
+  audio?: ChannelAudioInput;
 };
 
 export type WhatsappChannelConfig = {
@@ -94,6 +140,7 @@ export type WhatsappChannelConfig = {
   secrets: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
+  audio?: ChannelAudioConfig;
 };
 
 export type AgentChannel = WebsiteChannelConfig | TelegramChannelConfig | WhatsappChannelConfig;
@@ -210,6 +257,7 @@ export type ToolRenderResult = {
 export type ToolRenderContext<Input = unknown> = {
   input: Input;
   runtime: ToolRuntimeContext;
+  clock: ToolClockContext;
 };
 
 export type ToolRuntimeContext = {
@@ -219,10 +267,20 @@ export type ToolRuntimeContext = {
   database: "sqlite" | "turso" | "none";
 };
 
+export type ToolClockContext = {
+  now: Date;
+  isoTimestamp: string;
+  timeZone: string;
+  localDate: string;
+  localWeekday: string;
+  localDateTime: string;
+};
+
 export type ToolContext = {
   secrets: Record<string, string>;
   signal: AbortSignal;
   runtime: ToolRuntimeContext;
+  clock: ToolClockContext;
   database: DatabaseRunner;
   db: DatabaseRunner;
   storage: {
@@ -254,10 +312,12 @@ export type AgentConfig = {
   name: string;
   runtime: AgentRuntime;
   provider: AgentProvider;
+  timeZone?: string;
   instructions: string;
   secrets: string[];
   tools?: AgentTool[];
   channels?: AgentChannel[];
+  transcription?: AgentTranscriptionConfig;
   knowledge?: AgentKnowledgeConfig;
   access: {
     mode: AccessMode;
@@ -287,6 +347,7 @@ export function websiteChannel(input: WebsiteChannelInput): WebsiteChannelConfig
     secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"], "website channel"),
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "website channel") } : {}),
+    ...(input.audio ? { audio: normalizeChannelAudio(input.audio, "website channel") } : {}),
   };
 }
 
@@ -302,6 +363,7 @@ export function telegramChannel(input: TelegramChannelInput): TelegramChannelCon
     allowedUpdates: input.allowedUpdates ?? ["message"],
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "telegram channel") } : {}),
+    ...(input.audio ? { audio: normalizeChannelAudio(input.audio, "telegram channel") } : {}),
   };
 }
 
@@ -316,6 +378,7 @@ export function whatsappChannel(input: WhatsappChannelInput): WhatsappChannelCon
     ),
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, `${input.provider} whatsapp channel`) } : {}),
+    ...(input.audio ? { audio: normalizeChannelAudio(input.audio, `${input.provider} whatsapp channel`) } : {}),
   };
 }
 
@@ -370,6 +433,33 @@ function normalizeChannelBuffer(input: ChannelBufferInput, context: string): Cha
   return buffer;
 }
 
+function normalizeChannelAudio(input: ChannelAudioInput, context: string): ChannelAudioConfig {
+  const mode = input.mode ?? "transcribe";
+
+  if (mode !== "off" && mode !== "reject" && mode !== "transcribe") {
+    throw new Error(`${context} audio.mode must be "off", "reject", or "transcribe".`);
+  }
+
+  if (mode === "off") {
+    return { mode: "off" };
+  }
+
+  if (input.maxDurationSeconds !== undefined) {
+    validatePositiveInteger(input.maxDurationSeconds, `${context} audio.maxDurationSeconds`);
+  }
+
+  if (input.maxBytes !== undefined) {
+    validatePositiveInteger(input.maxBytes, `${context} audio.maxBytes`);
+  }
+
+  return {
+    mode,
+    fallbackMessage: input.fallbackMessage ?? "I received an audio message, but I could not transcribe it. Please send the message as text.",
+    ...(input.maxDurationSeconds !== undefined ? { maxDurationSeconds: input.maxDurationSeconds } : {}),
+    ...(input.maxBytes !== undefined ? { maxBytes: input.maxBytes } : {}),
+  };
+}
+
 function validatePositiveInteger(value: number, field: string): void {
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error(`${field} must be a positive integer.`);
@@ -379,7 +469,18 @@ function validatePositiveInteger(value: number, field: string): void {
 export { loadAgentCapsule, findAgentCapsuleRoot } from "./runtime/config";
 export { runAgentMessage, runAgentMessageFromCwd } from "./runtime/chat";
 export { listConversationsFromCwd, getConversationFromCwd } from "./runtime/conversations";
-export { runEvalsFromCwd } from "./runtime/evals";
+export { defineEval, runEvalsFromCwd } from "./runtime/evals";
+export type {
+  EvalCase,
+  EvalExpect,
+  EvalResponseExpectation,
+  EvalRunSummary,
+  EvalResult,
+  EvalToolsContainerExpectation,
+  EvalToolsExpectation,
+  EvalTurn,
+  ToolExpectation,
+} from "./runtime/evals";
 export { getConversationTraceFromCwd } from "./runtime/traces";
 export { runToolFromCwd } from "./runtime/tool-runner";
 export { startAgentDevServer } from "./runtime/dev-server";
@@ -390,10 +491,13 @@ export { AgentKitError } from "./runtime/errors";
 export type {
   ChannelAdapter,
   ChannelAdapterId,
+  ChannelAudioAttachment,
   ChannelDeliveryDirection,
   ChannelDeliveryState,
   ChannelEventKind,
   ChannelExternalIdentity,
+  ChannelMediaDownloadInput,
+  ChannelMediaDownloadResult,
   ChannelMessageContentType,
   ChannelMessageRole,
   ChannelSendInput,
@@ -406,3 +510,8 @@ export type {
   WebhookVerificationInput,
   WebhookVerificationResult,
 } from "./runtime/channels";
+export type {
+  TranscriptionAdapter,
+  TranscriptionInput,
+  TranscriptionResult,
+} from "./runtime/transcription";

package/src/providers/pi.ts

@@ -97,7 +97,7 @@ async function runPiProvider(input: ProviderRunInput): Promise<ProviderRunResult
         content: [
           {
             type: "text",
-            text: result.rendered?.text ?? JSON.stringify(result.output),
+            text: providerToolResultText(result),
           },
         ],
         isError: false,
@@ -109,6 +109,19 @@ async function runPiProvider(input: ProviderRunInput): Promise<ProviderRunResult
   throw new AgentKitError("runtime_error", `Pi provider exceeded ${MAX_TOOL_TURNS} tool turns.`);
 }
 
+export function providerToolResultText(result: {
+  name: string;
+  visibility?: "user" | "internal";
+  rendered?: { text?: string };
+  output: unknown;
+}): string {
+  if (result.visibility === "internal") {
+    return `Internal tool ${result.name} completed.`;
+  }
+
+  return result.rendered?.text ?? JSON.stringify(result.output);
+}
+
 async function runPiTurn(
   model: Model<any>,
   context: Parameters<typeof stream>[1],

package/src/providers/test.ts

@@ -37,6 +37,17 @@ export const testProviderAdapter: ProviderAdapter = {
       };
     }
 
+    const currentDate = answerCurrentDate(input.instructions, userMessage.content);
+
+    if (currentDate) {
+      return {
+        message: {
+          role: "assistant",
+          content: currentDate,
+        },
+      };
+    }
+
     const rememberedName = answerRememberedName(input.messages);
 
     if (rememberedName) {
@@ -95,6 +106,31 @@ function answerRememberedName(messages: AgentMessage[]): string | null {
   return null;
 }
 
+function answerCurrentDate(instructions: string, content: string): string | null {
+  if (!/(today|current date|what date|data de hoje|hoje)/i.test(content)) {
+    return null;
+  }
+
+  const localDate = readRuntimeContextValue(instructions, "Local date");
+
+  if (!localDate) {
+    return null;
+  }
+
+  const localWeekday = readRuntimeContextValue(instructions, "Local weekday");
+  const timeZone = readRuntimeContextValue(instructions, "Time zone");
+  const weekday = localWeekday ? ` (${localWeekday})` : "";
+  const zone = timeZone ? ` in ${timeZone}` : "";
+
+  return `Today is ${localDate}${weekday}${zone}.`;
+}
+
+function readRuntimeContextValue(instructions: string, label: string): string | null {
+  const escapedLabel = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = instructions.match(new RegExp(`^- ${escapedLabel}: (.+)$`, "m"));
+  return match?.[1]?.trim() || null;
+}
+
 function asksForName(content: string): boolean {
   return /what(?:'s| is) my name\??/i.test(content) || /(como|qual)\s+(é|e)\s*(o\s+)?meu nome\??/i.test(content);
 }

package/src/runtime/channel-test-harness.ts

@@ -8,9 +8,11 @@ import type { NormalizedChannelEvent, RawWebhookEvent } from "./channels";
 export type ChannelFixtureName =
   | "website-message"
   | "telegram-message"
+  | "telegram-audio-message"
   | "telegram-duplicate-message"
   | "telegram-malformed-payload"
   | "zapster-message"
+  | "zapster-audio-message"
   | "zapster-duplicate-message"
   | "zapster-unsupported-media";