@andreprado/agentkit 0.1.0-alpha.10

package/src/runtime/conversations.ts

@@ -0,0 +1,38 @@
+import { openCapsuleStore, type ConversationRecord, type ConversationSummary } from "../storage/sqlite";
+import { loadAgentCapsule } from "./config";
+import { AgentKitError } from "./errors";
+
+export async function listConversationsFromCwd(cwd = process.cwd()): Promise<ConversationSummary[]> {
+  const capsule = await loadAgentCapsule(cwd);
+  const store = await openCapsuleStore(capsule);
+
+  try {
+    return store.listConversations();
+  } finally {
+    store.close();
+  }
+}
+
+export async function getConversationFromCwd(
+  cwd: string,
+  conversationId: string,
+): Promise<ConversationRecord> {
+  if (!conversationId) {
+    throw new AgentKitError("validation_error", "Missing conversation id.");
+  }
+
+  const capsule = await loadAgentCapsule(cwd);
+  const store = await openCapsuleStore(capsule);
+
+  try {
+    const conversation = store.getConversation(conversationId);
+
+    if (!conversation) {
+      throw new AgentKitError("conversation_not_found", `Conversation "${conversationId}" was not found.`);
+    }
+
+    return conversation;
+  } finally {
+    store.close();
+  }
+}

package/src/runtime/core/deploy-state.ts

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { findAgentCapsuleRoot } from "../config";
+import type { RuntimeTargetId } from "./targets";
+
+export type LocalDeployState = {
+  project_id?: string;
+  deploy_id: string;
+  url?: string;
+  target: RuntimeTargetId;
+  runtime: "edge" | "container";
+  resources: Record<string, unknown>;
+  owner_state?: "anonymous" | "claimed";
+  access?: {
+    mode?: string;
+    private_token?: string;
+  };
+  created_at?: string;
+};
+
+export function normalizeDeployState(input: unknown): LocalDeployState | null {
+  if (!input || typeof input !== "object") {
+    return null;
+  }
+
+  const state = input as Partial<LocalDeployState>;
+
+  if (typeof state.deploy_id !== "string" || state.deploy_id.length === 0) {
+    return null;
+  }
+
+  return {
+    ...state,
+    deploy_id: state.deploy_id,
+    target: isRuntimeTarget(state.target) ? state.target : "cloudflare",
+    runtime: state.runtime === "container" ? "container" : "edge",
+    resources: state.resources && typeof state.resources === "object" ? state.resources : {},
+  };
+}
+
+export async function readLocalDeployStateIfExists(cwd: string): Promise<LocalDeployState | null> {
+  try {
+    const root = await findAgentCapsuleRoot(cwd);
+    const source = await readFile(join(root, ".agentkit/deploy.json"), "utf8");
+    return normalizeDeployState(JSON.parse(source));
+  } catch {
+    return null;
+  }
+}
+
+function isRuntimeTarget(value: unknown): value is RuntimeTargetId {
+  return value === "local" || value === "cloudflare" || value === "container" || value === "vps";
+}

package/src/runtime/core/manifest.ts

@@ -0,0 +1,213 @@
+import { relative, resolve } from "node:path";
+
+import type { AgentConfig, AgentTool } from "../../index";
+import type { LoadedAgentCapsule } from "../config";
+import { resolveKnowledgeConfig } from "../knowledge/config";
+import { KNOWLEDGE_SEARCH_TOOL_NAME } from "../knowledge/tool";
+
+export type ManifestSchema = {
+  source: string;
+  sha256: string;
+};
+
+export type SharedAgentManifest = {
+  schema_version: 1;
+  name: string;
+  runtime: AgentConfig["runtime"];
+  provider: AgentConfig["provider"];
+  prompt: string;
+  secrets: string[];
+  tools: Array<{
+    name: string;
+    description: string;
+    inputSchema: AgentTool["inputSchema"];
+    outputSchema?: AgentTool["outputSchema"];
+    secrets: string[];
+    permissions: string[];
+    timeoutMs: number | null;
+  }>;
+  channels: NonNullable<AgentConfig["channels"]>;
+  knowledge: {
+    enabled: boolean;
+    sources: Array<{
+      kind: "file" | "url";
+      value: string;
+      title: string | null;
+    }>;
+    embedding: {
+      provider: string;
+      model: string | null;
+      dimensions: number | null;
+      secret: string | null;
+    };
+    retrieval: {
+      topK: number;
+      hybrid: boolean;
+    };
+    internalTool: string | null;
+  };
+  access: AgentConfig["access"];
+  storage: {
+    driver: AgentConfig["storage"]["driver"];
+    database:
+      | {
+          driver: "none";
+        }
+      | {
+          driver: "turso";
+          schema: string | null;
+          schema_sha256: string | null;
+        };
+    files:
+      | {
+          driver: "none";
+        }
+      | {
+          driver: "object";
+          bucket: string;
+          prefix: string;
+          maxUploadBytes: number;
+        };
+  };
+};
+
+export function buildSharedAgentManifest(
+  capsule: LoadedAgentCapsule,
+  options: { databaseSchema?: ManifestSchema | null } = {},
+): SharedAgentManifest {
+  const requiredSecrets = new Set(capsule.config.secrets);
+  const database = buildDatabaseManifest(capsule, options.databaseSchema ?? null);
+  const files = buildFilesManifest(capsule);
+  const knowledge = resolveKnowledgeConfig(capsule.config);
+
+  if (capsule.config.access.mode === "private") {
+    requiredSecrets.add("AGENTKIT_PRIVATE_TOKEN");
+  }
+
+  if (capsule.config.access.mode === "token") {
+    requiredSecrets.add("AGENTKIT_ACCESS_TOKEN");
+  }
+
+  if (capsule.config.provider.name === "openai") {
+    requiredSecrets.add("OPENAI_API_KEY");
+  }
+
+  if (database.driver === "turso") {
+    requiredSecrets.add("TURSO_DATABASE_URL");
+    requiredSecrets.add("TURSO_AUTH_TOKEN");
+  }
+
+  if (knowledge.embedding.secret) {
+    requiredSecrets.add(knowledge.embedding.secret);
+  }
+
+  for (const tool of capsule.config.tools ?? []) {
+    for (const secret of tool.secrets ?? []) {
+      requiredSecrets.add(secret);
+    }
+  }
+
+  for (const channel of capsule.config.channels ?? []) {
+    for (const secret of channel.secrets) {
+      requiredSecrets.add(secret);
+    }
+  }
+
+  return {
+    schema_version: 1,
+    name: capsule.config.name,
+    runtime: capsule.config.runtime,
+    provider: capsule.config.provider,
+    prompt: toCapsulePath(capsule, capsule.instructionsPath),
+    secrets: Array.from(requiredSecrets).sort(),
+    tools: (capsule.config.tools ?? []).map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      outputSchema: tool.outputSchema,
+      secrets: [...(tool.secrets ?? [])].sort(),
+      permissions: [...(tool.permissions ?? [])].sort(),
+      timeoutMs: tool.timeoutMs ?? null,
+    })),
+    channels: capsule.config.channels ?? [],
+    knowledge: {
+      enabled: knowledge.enabled,
+      sources: knowledge.sources.map((source) => ({
+        kind: source.kind,
+        value: source.value,
+        title: source.title,
+      })),
+      embedding: knowledge.embedding,
+      retrieval: knowledge.retrieval,
+      internalTool: knowledge.enabled ? KNOWLEDGE_SEARCH_TOOL_NAME : null,
+    },
+    access: capsule.config.access,
+    storage: {
+      driver: capsule.config.storage.driver,
+      database,
+      files,
+    },
+  };
+}
+
+export function toCapsulePath(capsule: LoadedAgentCapsule, path: string): string {
+  const localPath = relative(capsule.root, path);
+  return localPath.length > 0 ? localPath : ".";
+}
+
+function buildDatabaseManifest(
+  capsule: LoadedAgentCapsule,
+  schema: ManifestSchema | null,
+): SharedAgentManifest["storage"]["database"] {
+  const database = capsule.config.storage.database;
+
+  if (!database || database.driver === "none") {
+    return { driver: "none" };
+  }
+
+  const schemaPath = database.schema ? resolve(capsule.root, database.schema) : null;
+
+  return {
+    driver: "turso",
+    schema: schemaPath ? toCapsulePath(capsule, schemaPath) : null,
+    schema_sha256: schema?.sha256 ?? null,
+  };
+}
+
+function buildFilesManifest(capsule: LoadedAgentCapsule): SharedAgentManifest["storage"]["files"] {
+  const files = capsule.config.storage.files;
+
+  if (!files || files.driver === "none") {
+    return { driver: "none" };
+  }
+
+  return {
+    driver: "object",
+    bucket: files.bucket ?? `agentkit-${slugify(capsule.config.name)}-files`,
+    prefix: normalizePrefix(files.prefix ?? capsule.config.name),
+    maxUploadBytes: files.maxUploadBytes ?? 10 * 1024 * 1024,
+  };
+}
+
+function slugify(value: string): string {
+  const slug = value
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+
+  return slug || "agent";
+}
+
+function normalizePrefix(value: string): string {
+  return value
+    .split("/")
+    .map((part) =>
+      part
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, ""),
+    )
+    .filter(Boolean)
+    .join("/");
+}

package/src/runtime/core/targets.ts

@@ -0,0 +1,133 @@
+import { AgentKitError } from "../errors";
+
+export const runtimeTargetIds = ["local", "cloudflare", "container", "vps"] as const;
+
+export type RuntimeTargetId = (typeof runtimeTargetIds)[number];
+export type RuntimeTargetCapabilityState = "available" | "planned" | "unsupported";
+export type RuntimeStorageCapability = "agentkit" | "durable-object-sqlite" | "local-sqlite" | "postgres";
+export type RuntimeFilesCapability = "none" | "r2" | "local-disk" | "s3-compatible";
+export type RuntimeChannelCapability = "website" | "telegram" | "whatsapp";
+export type RuntimeProviderSupport = "pi-local" | "edge-compatible" | "server-env";
+
+export type RuntimeTargetCapabilities = {
+  build: RuntimeTargetCapabilityState;
+  deploy: RuntimeTargetCapabilityState;
+  dev: RuntimeTargetCapabilityState;
+  storage: readonly RuntimeStorageCapability[];
+  files: readonly RuntimeFilesCapability[];
+  channels: readonly RuntimeChannelCapability[];
+  providers: readonly RuntimeProviderSupport[];
+};
+
+export type RuntimeTarget = {
+  id: RuntimeTargetId;
+  label: string;
+  capabilities: RuntimeTargetCapabilities;
+};
+
+export const runtimeTargets: Readonly<Record<RuntimeTargetId, RuntimeTarget>> = {
+  local: {
+    id: "local",
+    label: "Local dev server",
+    capabilities: {
+      build: "unsupported",
+      deploy: "unsupported",
+      dev: "available",
+      storage: ["local-sqlite"],
+      files: ["local-disk"],
+      channels: ["website"],
+      providers: ["pi-local"],
+    },
+  },
+  cloudflare: {
+    id: "cloudflare",
+    label: "Cloudflare Worker",
+    capabilities: {
+      build: "available",
+      deploy: "available",
+      dev: "planned",
+      storage: ["agentkit", "durable-object-sqlite", "postgres"],
+      files: ["none", "r2"],
+      channels: ["website", "telegram", "whatsapp"],
+      providers: ["edge-compatible"],
+    },
+  },
+  container: {
+    id: "container",
+    label: "Container runtime",
+    capabilities: {
+      build: "available",
+      deploy: "planned",
+      dev: "planned",
+      storage: ["local-sqlite", "postgres"],
+      files: ["none", "local-disk", "s3-compatible"],
+      channels: ["website", "telegram", "whatsapp"],
+      providers: ["server-env"],
+    },
+  },
+  vps: {
+    id: "vps",
+    label: "VPS handoff",
+    capabilities: {
+      build: "unsupported",
+      deploy: "available",
+      dev: "unsupported",
+      storage: ["local-sqlite", "postgres"],
+      files: ["none", "local-disk", "s3-compatible"],
+      channels: ["website", "telegram", "whatsapp"],
+      providers: ["server-env"],
+    },
+  },
+};
+
+export function resolveRuntimeTarget(id: string): RuntimeTarget {
+  if (isRuntimeTargetId(id)) {
+    return runtimeTargets[id];
+  }
+
+  throw new AgentKitError(
+    "unsupported_target",
+    `Unsupported target "${id}". Supported targets: ${runtimeTargetIds.join(", ")}.`,
+  );
+}
+
+export function resolveBuildTarget(id = "cloudflare"): RuntimeTarget {
+  const target = resolveRuntimeTarget(id);
+
+  if (target.capabilities.build !== "available") {
+    throw unsupportedCapability("build", target.id, listTargetsWithCapability("build"));
+  }
+
+  return target;
+}
+
+export function resolveDeployTarget(id = "cloudflare"): RuntimeTarget {
+  const target = resolveRuntimeTarget(id);
+
+  if (target.capabilities.deploy !== "available") {
+    throw unsupportedCapability("deploy", target.id, listTargetsWithCapability("deploy"));
+  }
+
+  return target;
+}
+
+export function isRuntimeTargetId(id: string): id is RuntimeTargetId {
+  return Object.prototype.hasOwnProperty.call(runtimeTargets, id);
+}
+
+export function listTargetsWithCapability(
+  capability: "build" | "deploy" | "dev",
+): readonly RuntimeTargetId[] {
+  return runtimeTargetIds.filter((id) => runtimeTargets[id].capabilities[capability] === "available");
+}
+
+function unsupportedCapability(
+  capability: "build" | "deploy" | "dev",
+  id: RuntimeTargetId,
+  supportedTargets: readonly RuntimeTargetId[],
+): AgentKitError {
+  return new AgentKitError(
+    "unsupported_target",
+    `Unsupported ${capability} target "${id}". Supported ${capability} targets: ${supportedTargets.join(", ")}.`,
+  );
+}

package/src/runtime/database.ts

@@ -0,0 +1,256 @@
+import { readdir, readFile } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { basename, relative, resolve } from "node:path";
+
+import type { DatabaseArgs, DatabaseResult, DatabaseRunner, DatabaseStatement } from "../index";
+import { openCapsuleStore, type SqliteAgentKitStore } from "../storage/sqlite";
+import type { LoadedAgentCapsule } from "./config";
+import { AgentKitError } from "./errors";
+
+export type LocalDatabasePrepareResult = {
+  store: SqliteAgentKitStore;
+  databasePath: string;
+  migrations: {
+    configured: boolean;
+    path: string | null;
+    applied: string[];
+    skipped: string[];
+  };
+  schema: {
+    configured: boolean;
+    applied: boolean;
+    path: string | null;
+  };
+};
+
+export async function openPreparedCapsuleStore(capsule: LoadedAgentCapsule): Promise<LocalDatabasePrepareResult> {
+  const store = await openCapsuleStore(capsule);
+
+  try {
+    const migrations = await applyCapsuleDatabaseMigrations(capsule, store);
+    const schema = await applyCapsuleDatabaseSchema(capsule, store);
+    return {
+      store,
+      databasePath: store.dbPath,
+      migrations,
+      schema,
+    };
+  } catch (error) {
+    store.close();
+    throw error;
+  }
+}
+
+export async function applyCapsuleDatabaseMigrations(
+  capsule: LoadedAgentCapsule,
+  store: SqliteAgentKitStore,
+): Promise<LocalDatabasePrepareResult["migrations"]> {
+  const database = capsule.config.storage.database;
+
+  if (!database || database.driver !== "turso") {
+    return {
+      configured: false,
+      path: null,
+      applied: [],
+      skipped: [],
+    };
+  }
+
+  const migrationsPath = resolve(capsule.root, database.migrations ?? "migrations");
+  const migrations = await readMigrationFiles(migrationsPath);
+
+  if (migrations.length === 0) {
+    return {
+      configured: false,
+      path: migrationsPath,
+      applied: [],
+      skipped: [],
+    };
+  }
+
+  try {
+    const result = store.applyApplicationMigrations(migrations);
+    return {
+      configured: true,
+      path: migrationsPath,
+      applied: result.applied,
+      skipped: result.skipped,
+    };
+  } catch (error) {
+    if (error instanceof AgentKitError && error.code === "database_schema_error") {
+      throw new AgentKitError(
+        "database_schema_error",
+        [
+          `Could not apply database migrations from ${relative(capsule.root, migrationsPath)}.`,
+          "Migrations must be ordered .sql files and should use safe, forward-only changes.",
+          error.message,
+        ].join(" "),
+        { cause: error },
+      );
+    }
+
+    throw error;
+  }
+}
+
+async function readMigrationFiles(directory: string): Promise<Array<{ id: string; sql: string }>> {
+  let entries: Dirent[];
+
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return [];
+    }
+
+    throw error;
+  }
+
+  const files = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".sql"))
+    .map((entry) => entry.name)
+    .sort();
+
+  return Promise.all(
+    files.map(async (file) => ({
+      id: basename(file, ".sql"),
+      sql: await readFile(resolve(directory, file), "utf8"),
+    })),
+  );
+}
+
+export async function applyCapsuleDatabaseSchema(
+  capsule: LoadedAgentCapsule,
+  store: SqliteAgentKitStore,
+): Promise<LocalDatabasePrepareResult["schema"]> {
+  const database = capsule.config.storage.database;
+
+  if (!database || database.driver !== "turso" || !database.schema) {
+    return {
+      configured: false,
+      applied: false,
+      path: null,
+    };
+  }
+
+  const schemaPath = resolve(capsule.root, database.schema);
+  let schema: string;
+
+  try {
+    schema = await readFile(schemaPath, "utf8");
+  } catch (error) {
+    throw new AgentKitError(
+      "database_schema_error",
+      `Could not read storage.database.schema at ${relative(capsule.root, schemaPath)}. Check storage.database.schema in agentkit.config.ts.`,
+      { cause: error },
+    );
+  }
+
+  try {
+    store.applyApplicationSchema(schema);
+  } catch (error) {
+    if (error instanceof AgentKitError && error.code === "database_schema_error") {
+      throw new AgentKitError(
+        "database_schema_error",
+        [
+          `Could not apply storage.database.schema at ${relative(capsule.root, schemaPath)}.`,
+          "schema.sql is a v1 bootstrap file and should be idempotent: use CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS, and only safe additive ALTER TABLE statements.",
+          "AgentKit does not run destructive schema changes or versioned migrations automatically in v1.",
+          error.message,
+        ].join(" "),
+        { cause: error },
+      );
+    }
+
+    throw error;
+  }
+
+  return {
+    configured: true,
+    applied: true,
+    path: schemaPath,
+  };
+}
+
+export function createLocalDatabaseRunner(store: SqliteAgentKitStore): DatabaseRunner {
+  const run = async (sql: string, args: DatabaseArgs = []): Promise<DatabaseResult> => {
+    validateSql(sql, args);
+    return store.executeApplicationSql(sql, args);
+  };
+
+  return Object.assign(run, {
+    execute: run,
+    query: run,
+    async transaction<T>(callback: (tx: DatabaseRunner) => Promise<T> | T): Promise<T> {
+      if (typeof callback !== "function") {
+        throw new AgentKitError("database_query_invalid", "ctx.db.transaction requires a callback.");
+      }
+
+      const tx = createLocalTransactionRunner(store);
+      return await Promise.resolve(store.runApplicationTransaction(() => callback(tx)));
+    },
+    async batch(statements: DatabaseStatement[]): Promise<DatabaseResult[]> {
+      validateStatements(statements);
+      return store.executeApplicationBatch(statements);
+    },
+  });
+}
+
+function createLocalTransactionRunner(store: SqliteAgentKitStore): DatabaseRunner {
+  const run = async (sql: string, args: DatabaseArgs = []): Promise<DatabaseResult> => {
+    validateSql(sql, args);
+    return store.executeApplicationSql(sql, args);
+  };
+
+  return Object.assign(run, {
+    execute: run,
+    query: run,
+    transaction(): Promise<never> {
+      throw new AgentKitError(
+        "database_transaction_unsupported",
+        "Nested database transactions are not supported. Use one ctx.db.transaction callback or ctx.db.batch call.",
+      );
+    },
+    async batch(statements: DatabaseStatement[]): Promise<DatabaseResult[]> {
+      validateStatements(statements);
+      return statements.map((statement) => store.executeApplicationSql(statement.sql, statement.args ?? []));
+    },
+  });
+}
+
+function validateSql(sql: string, args: DatabaseArgs): void {
+  if (typeof sql !== "string" || sql.trim().length === 0) {
+    throw new AgentKitError("database_query_invalid", "Database SQL must be a non-empty string.");
+  }
+
+  if (!Array.isArray(args)) {
+    throw new AgentKitError("database_query_invalid", "Database SQL args must be an array.");
+  }
+
+  for (const arg of args) {
+    if (arg !== null && typeof arg !== "string" && typeof arg !== "number" && typeof arg !== "boolean") {
+      throw new AgentKitError(
+        "database_query_invalid",
+        "Database SQL args may only contain strings, numbers, booleans, or null.",
+      );
+    }
+  }
+}
+
+function validateStatements(statements: DatabaseStatement[]): void {
+  if (!Array.isArray(statements)) {
+    throw new AgentKitError("database_query_invalid", "ctx.db.batch requires an array of statements.");
+  }
+
+  for (const [index, statement] of statements.entries()) {
+    if (!statement || typeof statement !== "object") {
+      throw new AgentKitError("database_query_invalid", `ctx.db.batch statement ${index} must be an object.`);
+    }
+
+    validateSql(statement.sql, statement.args ?? []);
+  }
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return typeof error === "object" && error !== null && "code" in error;
+}