@andreprado/agentkit 0.1.0-alpha.10

package/src/index.ts

@@ -0,0 +1,408 @@
+export type AgentRuntime = "local" | "edge";
+export type AgentProviderName = "test" | "openai" | "anthropic" | "openrouter" | "custom";
+export type AccessMode = "private" | "token" | "public";
+export type ToolVisibility = "user" | "internal";
+export type ChannelType = "website" | "telegram" | "whatsapp";
+export type ChannelProvider = "agentkit" | "telegram" | "zapster" | "meta";
+export type WhatsappChannelProvider = "zapster" | "meta";
+export type TelegramAllowedUpdate = "message";
+
+export type AgentProvider = {
+  name: AgentProviderName;
+  model: string;
+};
+
+export type ChannelLimits = {
+  messagesPerDay?: number;
+  usdPerDay?: number;
+};
+
+export type ChannelBufferMode = "off" | "debounce";
+
+export type ChannelBufferInput = {
+  mode?: ChannelBufferMode;
+  quietWindowMs?: number;
+  maxWaitMs?: number;
+  maxMessages?: number;
+  maxChars?: number;
+};
+
+export type ChannelBufferConfig =
+  | {
+      mode: "off";
+    }
+  | {
+      mode: "debounce";
+      quietWindowMs: number;
+      maxWaitMs: number;
+      maxMessages: number;
+      maxChars: number;
+    };
+
+export type WebsiteChannelAccess = {
+  mode: "token";
+};
+
+export type WebsiteChannelInput = {
+  name: string;
+  access?: WebsiteChannelAccess;
+  secrets?: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
+};
+
+export type WebsiteChannelConfig = {
+  type: "website";
+  provider: "agentkit";
+  name: string;
+  access: WebsiteChannelAccess;
+  secrets: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
+};
+
+export type TelegramChannelInput = {
+  name: string;
+  secrets?: string[];
+  allowedUpdates?: TelegramAllowedUpdate[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
+};
+
+export type TelegramChannelConfig = {
+  type: "telegram";
+  provider: "telegram";
+  name: string;
+  secrets: string[];
+  allowedUpdates: TelegramAllowedUpdate[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
+};
+
+export type WhatsappChannelInput = {
+  name: string;
+  provider: WhatsappChannelProvider;
+  secrets?: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
+};
+
+export type WhatsappChannelConfig = {
+  type: "whatsapp";
+  provider: WhatsappChannelProvider;
+  name: string;
+  secrets: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
+};
+
+export type AgentChannel = WebsiteChannelConfig | TelegramChannelConfig | WhatsappChannelConfig;
+
+export type AgentDatabaseConfig =
+  | {
+      driver: "none";
+    }
+  | {
+      driver: "turso";
+      schema?: string;
+      migrations?: string;
+    };
+
+export type AgentFilesConfig =
+  | {
+      driver: "none";
+    }
+  | {
+      driver: "r2";
+      bucket?: string;
+      prefix?: string;
+      maxUploadBytes?: number;
+    };
+
+export type AgentKnowledgeSource =
+  | string
+  | {
+      path: string;
+      title?: string;
+    }
+  | {
+      url: string;
+      title?: string;
+    };
+
+export type AgentKnowledgeEmbeddingProvider = "none" | "test" | "openai";
+
+export type AgentKnowledgeEmbeddingConfig = {
+  provider?: AgentKnowledgeEmbeddingProvider;
+  model?: string;
+  dimensions?: number;
+  secret?: string;
+};
+
+export type AgentKnowledgeRetrievalConfig = {
+  topK?: number;
+  hybrid?: boolean;
+};
+
+export type AgentKnowledgeConfig = {
+  sources?: AgentKnowledgeSource[];
+  embedding?: AgentKnowledgeEmbeddingConfig;
+  retrieval?: AgentKnowledgeRetrievalConfig;
+};
+
+export type JsonSchema = {
+  type: string | string[];
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  [key: string]: unknown;
+};
+
+export type DatabaseValue = string | number | boolean | null;
+export type DatabaseArgs = readonly DatabaseValue[];
+export type DatabaseRow = Record<string, DatabaseValue>;
+export type DatabaseResult = {
+  rows: DatabaseRow[];
+  rowsAffected: number;
+  lastInsertRowid: number | string | null;
+  columns: string[];
+};
+export type DatabaseStatement = {
+  sql: string;
+  args?: DatabaseArgs;
+};
+export type DatabaseRunner = {
+  (sql: string, args?: DatabaseArgs): Promise<DatabaseResult>;
+  execute(sql: string, args?: DatabaseArgs): Promise<DatabaseResult>;
+  query(sql: string, args?: DatabaseArgs): Promise<DatabaseResult>;
+  transaction<T>(callback: (tx: DatabaseRunner) => Promise<T> | T): Promise<T>;
+  batch(statements: DatabaseStatement[]): Promise<DatabaseResult[]>;
+};
+
+export type ToolRenderField = {
+  label: string;
+  value: string;
+};
+
+export type ToolRenderAction = {
+  label: string;
+  href?: string;
+};
+
+export type ToolRenderBlock =
+  | {
+      type: "text";
+      text: string;
+    }
+  | {
+      type: "card";
+      title: string;
+      subtitle?: string;
+      fields?: ToolRenderField[];
+      actions?: ToolRenderAction[];
+    };
+
+export type ToolRenderResult = {
+  text: string;
+  blocks?: ToolRenderBlock[];
+};
+
+export type ToolRenderContext<Input = unknown> = {
+  input: Input;
+  runtime: ToolRuntimeContext;
+};
+
+export type ToolRuntimeContext = {
+  environment: "local" | "hosted" | "eval" | "test";
+  invocation: "chat" | "tool" | "dev" | "channel" | "eval" | "sync";
+  target: "bun" | "cloudflare";
+  database: "sqlite" | "turso" | "none";
+};
+
+export type ToolContext = {
+  secrets: Record<string, string>;
+  signal: AbortSignal;
+  runtime: ToolRuntimeContext;
+  database: DatabaseRunner;
+  db: DatabaseRunner;
+  storage: {
+    sql: DatabaseRunner;
+  };
+};
+
+export type SyncContext = {
+  env: Record<string, string | undefined>;
+  database: DatabaseRunner;
+  db: DatabaseRunner;
+  runtime: ToolRuntimeContext;
+};
+
+export type AgentTool<Input = unknown, Output = unknown> = {
+  name: string;
+  description: string;
+  visibility?: ToolVisibility;
+  inputSchema: JsonSchema;
+  outputSchema?: JsonSchema;
+  secrets?: string[];
+  permissions?: string[];
+  timeoutMs?: number;
+  execute(input: Input, ctx: ToolContext): Promise<Output> | Output;
+  render?(output: Output, ctx: ToolRenderContext<Input>): string | ToolRenderResult;
+};
+
+export type AgentConfig = {
+  name: string;
+  runtime: AgentRuntime;
+  provider: AgentProvider;
+  instructions: string;
+  secrets: string[];
+  tools?: AgentTool[];
+  channels?: AgentChannel[];
+  knowledge?: AgentKnowledgeConfig;
+  access: {
+    mode: AccessMode;
+  };
+  storage: {
+    driver: "sqlite" | "agentkit";
+    path?: string;
+    database?: AgentDatabaseConfig;
+    files?: AgentFilesConfig;
+  };
+};
+
+export function defineAgent(config: AgentConfig): AgentConfig {
+  return config;
+}
+
+export function defineTool<Input = unknown, Output = unknown>(tool: AgentTool<Input, Output>): AgentTool<Input, Output> {
+  return tool;
+}
+
+export function websiteChannel(input: WebsiteChannelInput): WebsiteChannelConfig {
+  return {
+    type: "website",
+    provider: "agentkit",
+    name: input.name,
+    access: input.access ?? { mode: "token" },
+    secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"], "website channel"),
+    ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "website channel") } : {}),
+  };
+}
+
+export function telegramChannel(input: TelegramChannelInput): TelegramChannelConfig {
+  return {
+    type: "telegram",
+    provider: "telegram",
+    name: input.name,
+    secrets: normalizeChannelSecrets(
+      input.secrets ?? ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"],
+      "telegram channel",
+    ),
+    allowedUpdates: input.allowedUpdates ?? ["message"],
+    ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "telegram channel") } : {}),
+  };
+}
+
+export function whatsappChannel(input: WhatsappChannelInput): WhatsappChannelConfig {
+  return {
+    type: "whatsapp",
+    provider: input.provider,
+    name: input.name,
+    secrets: normalizeChannelSecrets(
+      input.secrets ?? defaultWhatsappChannelSecrets(input.provider),
+      `${input.provider} whatsapp channel`,
+    ),
+    ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, `${input.provider} whatsapp channel`) } : {}),
+  };
+}
+
+function defaultWhatsappChannelSecrets(provider: WhatsappChannelProvider): string[] {
+  if (provider === "zapster") {
+    return ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"];
+  }
+
+  return ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"];
+}
+
+function normalizeChannelSecrets(secrets: string[], context: string): string[] {
+  const uniqueSecrets = new Set<string>();
+
+  for (const secret of secrets) {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(secret)) {
+      throw new Error(`${context} secrets must be environment variable names, not secret values.`);
+    }
+
+    uniqueSecrets.add(secret);
+  }
+
+  return Array.from(uniqueSecrets).sort();
+}
+
+function normalizeChannelBuffer(input: ChannelBufferInput, context: string): ChannelBufferConfig {
+  if (input.mode === "off") {
+    return { mode: "off" };
+  }
+
+  if (input.mode !== undefined && input.mode !== "debounce") {
+    throw new Error(`${context} buffer.mode must be "off" or "debounce".`);
+  }
+
+  const buffer: ChannelBufferConfig = {
+    mode: "debounce",
+    quietWindowMs: input.quietWindowMs ?? 2500,
+    maxWaitMs: input.maxWaitMs ?? 12000,
+    maxMessages: input.maxMessages ?? 20,
+    maxChars: input.maxChars ?? 8000,
+  };
+
+  validatePositiveInteger(buffer.quietWindowMs, `${context} buffer.quietWindowMs`);
+  validatePositiveInteger(buffer.maxWaitMs, `${context} buffer.maxWaitMs`);
+  validatePositiveInteger(buffer.maxMessages, `${context} buffer.maxMessages`);
+  validatePositiveInteger(buffer.maxChars, `${context} buffer.maxChars`);
+
+  if (buffer.maxWaitMs < buffer.quietWindowMs) {
+    throw new Error(`${context} buffer.maxWaitMs must be greater than or equal to buffer.quietWindowMs.`);
+  }
+
+  return buffer;
+}
+
+function validatePositiveInteger(value: number, field: string): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${field} must be a positive integer.`);
+  }
+}
+
+export { loadAgentCapsule, findAgentCapsuleRoot } from "./runtime/config";
+export { runAgentMessage, runAgentMessageFromCwd } from "./runtime/chat";
+export { listConversationsFromCwd, getConversationFromCwd } from "./runtime/conversations";
+export { runEvalsFromCwd } from "./runtime/evals";
+export { getConversationTraceFromCwd } from "./runtime/traces";
+export { runToolFromCwd } from "./runtime/tool-runner";
+export { startAgentDevServer } from "./runtime/dev-server";
+export { inspectAgentCapsule } from "./runtime/inspect";
+export { buildAgentCapsule } from "./runtime/build";
+export { deployBuildToAgentKitCloud } from "./runtime/deploy";
+export { AgentKitError } from "./runtime/errors";
+export type {
+  ChannelAdapter,
+  ChannelAdapterId,
+  ChannelDeliveryDirection,
+  ChannelDeliveryState,
+  ChannelEventKind,
+  ChannelExternalIdentity,
+  ChannelMessageContentType,
+  ChannelMessageRole,
+  ChannelSendInput,
+  ChannelSendResult,
+  ChannelStatusInput,
+  ChannelStatusResult,
+  NormalizedChannelEvent,
+  NormalizedChannelMessage,
+  RawWebhookEvent,
+  WebhookVerificationInput,
+  WebhookVerificationResult,
+} from "./runtime/channels";

package/src/providers/index.ts

@@ -0,0 +1,25 @@
+import type { AgentProvider } from "../index";
+import { AgentKitError } from "../runtime/errors";
+import { piProviderAdapters } from "./pi";
+import { testProviderAdapter } from "./test";
+import type { ProviderAdapter } from "./types";
+
+const providerAdapters = new Map<string, ProviderAdapter>([
+  [testProviderAdapter.name, testProviderAdapter],
+  ...piProviderAdapters.map((adapter) => [adapter.name, adapter] as const),
+]);
+
+export function getProviderAdapter(provider: AgentProvider): ProviderAdapter {
+  const adapter = providerAdapters.get(provider.name);
+
+  if (!adapter) {
+    throw new AgentKitError(
+      "provider_not_supported",
+      `Provider "${provider.name}" is not implemented in this AgentKit runtime yet.`,
+    );
+  }
+
+  return adapter;
+}
+
+export type { AgentMessage, AgentMessageRole, ProviderAdapter, ProviderRunInput, ProviderRunResult } from "./types";

package/src/providers/pi.ts

@@ -0,0 +1,286 @@
+import {
+  findEnvKeys,
+  getModel,
+  getModels,
+  stream,
+  type AssistantMessage,
+  type AssistantMessageEvent,
+  type Message,
+  type Model,
+  type Provider,
+  type Tool as PiTool,
+  type ToolCall,
+  type Usage,
+} from "@earendil-works/pi-ai";
+
+import type { AgentProviderName, AgentTool } from "../index";
+import { AgentKitError } from "../runtime/errors";
+import type { ProviderAdapter, ProviderRunInput, ProviderRunResult } from "./types";
+
+const PI_PROVIDER_NAMES = ["openai", "anthropic", "openrouter"] as const satisfies AgentProviderName[];
+const MAX_TOOL_TURNS = 8;
+
+export const piProviderAdapters: ProviderAdapter[] = PI_PROVIDER_NAMES.map((name) => ({
+  name,
+  run(input) {
+    return runPiProvider(input);
+  },
+}));
+
+async function runPiProvider(input: ProviderRunInput): Promise<ProviderRunResult> {
+  const provider = toPiProvider(input.agent.provider.name);
+  const apiKey = requireProviderApiKey(provider, input.env ?? process.env);
+  const model = resolveModel(provider, input.agent.provider.model);
+  const messages = toPiMessages(input.messages);
+  const tools = input.tools.map(toPiTool);
+  const rawMessages: AssistantMessage[] = [];
+  const rawEvents: AssistantMessageEvent[] = [];
+  let usage: Usage | undefined;
+
+  for (let turn = 0; turn < MAX_TOOL_TURNS; turn += 1) {
+    const assistant = await runPiTurn(
+      model,
+      {
+        systemPrompt: input.instructions,
+        messages,
+        tools,
+      },
+      {
+        apiKey,
+        signal: input.signal,
+      },
+      rawEvents,
+    );
+    rawMessages.push(assistant);
+    usage = addUsage(usage, assistant.usage);
+
+    if (assistant.stopReason === "error" || assistant.stopReason === "aborted") {
+      throw new AgentKitError(
+        assistant.stopReason === "aborted" ? "runtime_aborted" : "runtime_error",
+        assistant.errorMessage ?? `Pi provider "${provider}" returned stop reason "${assistant.stopReason}".`,
+      );
+    }
+
+    const toolCalls = assistant.content.filter((block): block is ToolCall => block.type === "toolCall");
+
+    if (toolCalls.length === 0) {
+      return {
+        message: {
+          role: "assistant",
+          content: assistantText(assistant),
+        },
+        usage: normalizeUsage(usage),
+        raw: {
+          provider: "pi",
+          events: rawEvents,
+          messages: rawMessages,
+        },
+      };
+    }
+
+    if (!input.toolRuntime) {
+      throw new AgentKitError("runtime_error", "The runtime did not provide a tool registry.");
+    }
+
+    messages.push(assistant);
+
+    for (const toolCall of toolCalls) {
+      const result = await input.toolRuntime.execute({
+        name: toolCall.name,
+        input: toolCall.arguments,
+      });
+
+      messages.push({
+        role: "toolResult",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        content: [
+          {
+            type: "text",
+            text: result.rendered?.text ?? JSON.stringify(result.output),
+          },
+        ],
+        isError: false,
+        timestamp: Date.now(),
+      });
+    }
+  }
+
+  throw new AgentKitError("runtime_error", `Pi provider exceeded ${MAX_TOOL_TURNS} tool turns.`);
+}
+
+async function runPiTurn(
+  model: Model<any>,
+  context: Parameters<typeof stream>[1],
+  options: Parameters<typeof stream>[2],
+  rawEvents: AssistantMessageEvent[],
+): Promise<AssistantMessage> {
+  const eventStream = stream(model, context, options);
+  let assistant: AssistantMessage | undefined;
+  let failed: AssistantMessage | undefined;
+
+  for await (const event of eventStream) {
+    rawEvents.push(event);
+
+    if (event.type === "done") {
+      assistant = event.message;
+    }
+
+    if (event.type === "error") {
+      failed = event.error;
+    }
+  }
+
+  if (failed) {
+    return failed;
+  }
+
+  if (!assistant) {
+    throw new AgentKitError("runtime_error", "Pi provider stream ended without a final assistant message.");
+  }
+
+  return assistant;
+}
+
+function toPiProvider(provider: string): Provider {
+  if (provider === "openai" || provider === "anthropic" || provider === "openrouter") {
+    return provider;
+  }
+
+  throw new AgentKitError("provider_not_supported", `Provider "${provider}" is not supported by the Pi adapter yet.`);
+}
+
+function requireProviderApiKey(provider: Provider, env: Record<string, string | undefined>): string {
+  const envNames = findEnvKeys(provider) ?? defaultProviderSecretNames(provider);
+  const setName = envNames.find((name) => env[name]);
+
+  if (!setName) {
+    throw new AgentKitError(
+      "secret_not_found",
+      `Provider "${provider}" requires ${formatSecretList(envNames)}. Set it in .env or the process environment.`,
+    );
+  }
+
+  return env[setName] as string;
+}
+
+function defaultProviderSecretNames(provider: Provider): string[] {
+  return [`${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`];
+}
+
+function formatSecretList(names: string[]): string {
+  if (names.length === 1) {
+    return names[0];
+  }
+
+  return `one of: ${names.join(", ")}`;
+}
+
+function resolveModel(provider: Provider, modelId: string): Model<any> {
+  const modelExists = getModels(provider as any).some((model) => model.id === modelId);
+
+  if (!modelExists) {
+    throw new AgentKitError(
+      "provider_model_unsupported",
+      `Pi SDK could not resolve provider "${provider}" model "${modelId}".`,
+    );
+  }
+
+  try {
+    return getModel(provider as any, modelId as any) as Model<any>;
+  } catch (error) {
+    throw new AgentKitError(
+      "provider_model_unsupported",
+      `Pi SDK could not resolve provider "${provider}" model "${modelId}".`,
+      { cause: error },
+    );
+  }
+}
+
+function toPiMessages(messages: ProviderRunInput["messages"]): Message[] {
+  return messages.map((message) => ({
+    role: message.role === "assistant" ? "assistant" : "user",
+    content: [
+      {
+        type: "text",
+        text: message.content,
+      },
+    ],
+    timestamp: Date.now(),
+    ...(message.role === "assistant"
+      ? {
+          api: "agentkit",
+          provider: "agentkit",
+          model: "agentkit",
+          usage: emptyUsage(),
+          stopReason: "stop",
+        }
+      : {}),
+  })) as Message[];
+}
+
+function toPiTool(tool: AgentTool): PiTool {
+  return {
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.inputSchema as PiTool["parameters"],
+  };
+}
+
+function assistantText(message: AssistantMessage): string {
+  return message.content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text)
+    .join("\n")
+    .trim();
+}
+
+function normalizeUsage(usage: Usage | undefined): ProviderRunResult["usage"] | undefined {
+  if (!usage) {
+    return undefined;
+  }
+
+  return {
+    inputTokens: usage.input,
+    outputTokens: usage.output,
+    totalTokens: usage.totalTokens,
+  };
+}
+
+function addUsage(current: Usage | undefined, next: Usage): Usage {
+  if (!current) {
+    return next;
+  }
+
+  return {
+    input: current.input + next.input,
+    output: current.output + next.output,
+    cacheRead: current.cacheRead + next.cacheRead,
+    cacheWrite: current.cacheWrite + next.cacheWrite,
+    totalTokens: current.totalTokens + next.totalTokens,
+    cost: {
+      input: current.cost.input + next.cost.input,
+      output: current.cost.output + next.cost.output,
+      cacheRead: current.cost.cacheRead + next.cost.cacheRead,
+      cacheWrite: current.cost.cacheWrite + next.cost.cacheWrite,
+      total: current.cost.total + next.cost.total,
+    },
+  };
+}
+
+function emptyUsage(): Usage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      total: 0,
+    },
+  };
+}