@andreprado/agentkit 0.1.0-alpha.10

package/src/cli/process.ts

@@ -0,0 +1,31 @@
+import { spawn } from "node:child_process";
+
+export function runInheritedCommand(command: string, args: string[], cwd: string): Promise<number> {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: "inherit",
+    });
+
+    child.once("error", reject);
+    child.once("close", (code) => resolvePromise(code ?? 1));
+  });
+}
+
+export async function waitForShutdown(stop: () => Promise<void>): Promise<void> {
+  await new Promise<void>((resolve) => {
+    let stopped = false;
+
+    const shutdown = () => {
+      if (stopped) {
+        return;
+      }
+
+      stopped = true;
+      void stop().finally(resolve);
+    };
+
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+  });
+}

package/src/cloud/artifact.ts

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { extname, isAbsolute, relative, resolve } from "node:path";
+
+import type { AgentBuildResult, AgentManifestWithBundle } from "../runtime/targets/cloudflare/build";
+import { AgentKitError } from "../runtime/errors";
+import type { HostedDeployArtifact } from "./contracts";
+
+const HOSTED_KNOWLEDGE_MAX_SOURCE_BYTES = 5 * 1024 * 1024;
+const HOSTED_KNOWLEDGE_MAX_TOTAL_BYTES = 9 * 1024 * 1024;
+const HOSTED_KNOWLEDGE_SUPPORTED_EXTENSIONS = new Set([".md", ".markdown", ".txt", ".csv"]);
+
+export async function createHostedDeployArtifact(build: AgentBuildResult): Promise<HostedDeployArtifact> {
+  const [manifestSource, workerSource, wranglerSource] = await Promise.all([
+    readFile(build.manifestPath, "utf8"),
+    readFile(build.workerPath, "utf8"),
+    readFile(build.wranglerPath, "utf8"),
+  ]);
+  const manifest = JSON.parse(manifestSource) as AgentManifestWithBundle;
+  const workerSha256 = sha256(workerSource);
+
+  if (workerSha256 !== build.bundleSha256 || workerSha256 !== manifest.bundle.sha256) {
+    throw new AgentKitError("artifact_integrity_error", "Worker SHA-256 does not match the build manifest.");
+  }
+
+  const artifact: HostedDeployArtifact = {
+    manifest,
+    worker: {
+      content_type: "application/javascript",
+      source: workerSource,
+      sha256: workerSha256,
+    },
+    wrangler: {
+      content_type: "application/json",
+      source: wranglerSource,
+    },
+  };
+
+  if (build.tursoSchemaPath) {
+    const source = await readFile(build.tursoSchemaPath, "utf8");
+    artifact.turso_schema = {
+      content_type: "text/sql",
+      source,
+      sha256: sha256(source),
+    };
+  }
+
+  if (manifest.knowledge.enabled) {
+    artifact.knowledge_sources = await createHostedKnowledgeSources(build.root, manifest);
+  }
+
+  return artifact;
+}
+
+async function createHostedKnowledgeSources(
+  root: string,
+  manifest: AgentManifestWithBundle,
+): Promise<NonNullable<HostedDeployArtifact["knowledge_sources"]>> {
+  const sources: NonNullable<HostedDeployArtifact["knowledge_sources"]>["sources"] = [];
+  let totalBytes = 0;
+
+  for (const source of manifest.knowledge.sources) {
+    if (source.kind === "url") {
+      throw new AgentKitError(
+        "artifact_knowledge_source_unsupported",
+        "Hosted deploy can automatically sync local Knowledge files only. URL Knowledge sources require a hosted ingestion connector.",
+      );
+    }
+
+    const absolutePath = resolve(root, source.value);
+    const sourceKey = capsuleRelativePath(root, absolutePath);
+    const extension = extname(sourceKey).toLowerCase();
+
+    if (!HOSTED_KNOWLEDGE_SUPPORTED_EXTENSIONS.has(extension)) {
+      throw new AgentKitError(
+        "artifact_knowledge_source_unsupported",
+        `Knowledge source "${sourceKey}" is not supported for hosted deploy. Use .md, .txt, or .csv.`,
+      );
+    }
+
+    const stats = await stat(absolutePath).catch((error) => {
+      throw new AgentKitError("artifact_knowledge_source_missing", `Knowledge source "${sourceKey}" was not found.`, {
+        cause: error,
+      });
+    });
+
+    if (!stats.isFile()) {
+      throw new AgentKitError("artifact_knowledge_source_invalid", `Knowledge source "${sourceKey}" must be a file.`);
+    }
+
+    if (stats.size > HOSTED_KNOWLEDGE_MAX_SOURCE_BYTES) {
+      throw new AgentKitError(
+        "artifact_knowledge_source_too_large",
+        `Knowledge source "${sourceKey}" is too large for automatic deploy sync. Keep each source under 5MB.`,
+      );
+    }
+
+    totalBytes += stats.size;
+
+    if (totalBytes > HOSTED_KNOWLEDGE_MAX_TOTAL_BYTES) {
+      throw new AgentKitError(
+        "artifact_knowledge_sources_too_large",
+        "Knowledge sources are too large for automatic deploy sync. Keep total packaged Knowledge under 9MB.",
+      );
+    }
+
+    const content = await readFile(absolutePath, "utf8");
+    sources.push({
+      kind: "file",
+      source_key: sourceKey,
+      title: source.title,
+      content,
+      sha256: sha256(content),
+    });
+  }
+
+  return {
+    content_type: "application/json",
+    sources,
+    sha256: sha256(JSON.stringify(sources)),
+  };
+}
+
+function capsuleRelativePath(root: string, absolutePath: string): string {
+  const relativePath = relative(root, absolutePath);
+
+  if (!relativePath || relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new AgentKitError(
+      "artifact_knowledge_source_outside_capsule",
+      "Knowledge source paths must stay inside the Agent Capsule.",
+    );
+  }
+
+  return relativePath.split("\\").join("/");
+}
+
+function sha256(source: string): string {
+  return createHash("sha256").update(source).digest("hex");
+}

package/src/cloud/client.ts

@@ -0,0 +1,79 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { AgentBuildResult } from "../runtime/targets/cloudflare/build";
+import type { LocalDeployState } from "../runtime/core/deploy-state";
+import { AgentKitError } from "../runtime/errors";
+import { createHostedDeployArtifact } from "./artifact";
+import type { AgentKitCloudDeployOptions, CreateDeployRequest, CreateDeployResponse } from "./contracts";
+
+export async function deployBuildToAgentKitCloud(
+  build: AgentBuildResult,
+  options: AgentKitCloudDeployOptions,
+): Promise<CreateDeployResponse> {
+  const artifact = await createHostedDeployArtifact(build);
+  const headers = new Headers({
+    "Content-Type": "application/json",
+  });
+  const apiToken = options.apiToken ?? process.env.AGENTKIT_CLOUD_API_TOKEN;
+
+  if (apiToken) {
+    headers.set("Authorization", `Bearer ${apiToken}`);
+  }
+
+  const response = await fetch(new URL("/v1/deploys", normalizeApiUrl(options.apiUrl)), {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      project_name: artifact.manifest.name,
+      anonymous: options.anonymous ?? !apiToken,
+      artifact,
+    } satisfies CreateDeployRequest),
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    const code =
+      payload && typeof payload === "object" && "error" in payload
+        ? String((payload as { error?: { code?: unknown } }).error?.code ?? "cloud_deploy_failed")
+        : "cloud_deploy_failed";
+    const message =
+      payload && typeof payload === "object" && "error" in payload
+        ? String((payload as { error?: { message?: unknown } }).error?.message ?? "AgentKit Cloud deploy failed.")
+        : `AgentKit Cloud deploy failed with HTTP ${response.status}.`;
+    throw new AgentKitError(code, message);
+  }
+
+  return payload as CreateDeployResponse;
+}
+
+export async function writeLocalDeployState(root: string, deploy: CreateDeployResponse): Promise<string> {
+  const statePath = join(root, ".agentkit/deploy.json");
+  const state: LocalDeployState = {
+    project_id: deploy.project.id,
+    deploy_id: deploy.deploy.id,
+    url: deploy.deploy.url,
+    target: "cloudflare",
+    runtime: "edge",
+    resources: {
+      cloudflare: {
+        worker_url: deploy.deploy.url,
+        durable_object_class: "AgentKitConversationStore",
+      },
+    },
+    owner_state: deploy.project.owner_state,
+    access: {
+      mode: deploy.deploy.access.mode,
+      private_token: deploy.deploy.access.private_token ?? undefined,
+    },
+    created_at: new Date().toISOString(),
+  };
+
+  await mkdir(join(root, ".agentkit"), { recursive: true });
+  await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  return statePath;
+}
+
+function normalizeApiUrl(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}

package/src/cloud/contracts.ts

@@ -0,0 +1,63 @@
+import type { AgentManifestWithBundle } from "../runtime/targets/cloudflare/build";
+
+export type HostedDeployArtifact = {
+  manifest: AgentManifestWithBundle;
+  worker: {
+    content_type: "application/javascript";
+    source: string;
+    sha256: string;
+  };
+  wrangler: {
+    content_type: "application/json";
+    source: string;
+  };
+  turso_schema?: {
+    content_type: "text/sql";
+    source: string;
+    sha256: string;
+  };
+  knowledge_sources?: {
+    content_type: "application/json";
+    sources: Array<{
+      kind: "file";
+      source_key: string;
+      title: string | null;
+      content: string;
+      sha256: string;
+    }>;
+    sha256: string;
+  };
+};
+
+export type CreateDeployRequest = {
+  project_name: string;
+  anonymous: boolean;
+  artifact: HostedDeployArtifact;
+};
+
+export type CreateDeployResponse = {
+  project: {
+    id: string;
+    owner_state: "anonymous" | "claimed";
+  };
+  deploy: {
+    id: string;
+    status: "ready" | "failed";
+    url: string;
+    access: {
+      mode: string;
+      private_token?: string;
+    };
+    knowledge?: {
+      enabled: boolean;
+      sources: number;
+      chunks: number;
+    };
+  };
+};
+
+export type AgentKitCloudDeployOptions = {
+  apiUrl: string;
+  apiToken?: string;
+  anonymous?: boolean;
+};

package/src/cloud/index.ts

@@ -0,0 +1,3 @@
+export * from "./artifact";
+export * from "./client";
+export * from "./contracts";

package/src/create-project.ts

@@ -0,0 +1,177 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+import { getTemplate, type TemplateFile } from "./templates";
+
+const execFileAsync = promisify(execFile);
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+
+export type CreateProjectOptions = {
+  name: string;
+  template: string;
+  cwd: string;
+};
+
+export type CreateProjectResult = {
+  name: string;
+  path: string;
+  files: string[];
+};
+
+export async function createProject(options: CreateProjectOptions): Promise<CreateProjectResult> {
+  const target = resolveProjectTarget(options);
+  validateProjectName(target.name);
+
+  const template = getTemplate(options.template);
+  const projectPath = target.path;
+  const files = [
+    ...template.files(target.name, {
+      agentkitDependency: await resolveAgentKitDependency(),
+    }),
+    ...(await loadDefaultSkillFiles()),
+  ];
+
+  if (target.currentDirectory) {
+    await ensureNoFileCollisions(projectPath, files.map((file) => file.path));
+  } else {
+    await mkdir(projectPath, { recursive: false });
+  }
+
+  for (const file of files) {
+    const absolutePath = join(projectPath, file.path);
+    const directory = absolutePath.slice(0, absolutePath.lastIndexOf("/"));
+
+    await mkdir(directory, { recursive: true });
+    await writeFile(absolutePath, file.contents);
+  }
+
+  await initializeGitRepository(projectPath);
+
+  return {
+    name: target.name,
+    path: projectPath,
+    files: files.map((file) => file.path),
+  };
+}
+
+function resolveProjectTarget(options: CreateProjectOptions): { name: string; path: string; currentDirectory: boolean } {
+  if (options.name === ".") {
+    const path = resolve(options.cwd);
+    return {
+      name: basename(path),
+      path,
+      currentDirectory: true,
+    };
+  }
+
+  return {
+    name: options.name,
+    path: join(options.cwd, options.name),
+    currentDirectory: false,
+  };
+}
+
+function validateProjectName(name: string) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9-_]*$/.test(name)) {
+    throw new Error("Project name must start with a letter or number and contain only letters, numbers, hyphens, and underscores.");
+  }
+}
+
+async function ensureNoFileCollisions(projectPath: string, files: string[]): Promise<void> {
+  const collisions: string[] = [];
+
+  for (const file of files) {
+    if (await pathExists(join(projectPath, file))) {
+      collisions.push(file);
+    }
+  }
+
+  if (collisions.length > 0) {
+    throw new Error(`Cannot create Agent Capsule in current directory because these files already exist: ${collisions.join(", ")}`);
+  }
+}
+
+async function initializeGitRepository(projectPath: string): Promise<void> {
+  if (await directoryExists(join(projectPath, ".git"))) {
+    return;
+  }
+
+  try {
+    await execFileAsync("git", ["init"], { cwd: projectPath });
+  } catch (error) {
+    const stderr = error && typeof error === "object" && "stderr" in error ? String(error.stderr) : "";
+    throw new Error(`Could not initialize git repository: ${stderr.trim() || "git init failed"}`);
+  }
+}
+
+async function resolveAgentKitDependency(): Promise<string> {
+  if (process.env.AGENTKIT_TEMPLATE_DEPENDENCY) {
+    return process.env.AGENTKIT_TEMPLATE_DEPENDENCY;
+  }
+
+  const packageRoot = resolve(moduleDir, "..");
+
+  if (await directoryExists(resolve(packageRoot, "../..", ".git"))) {
+    return `file:${packageRoot}`;
+  }
+
+  const packageJson = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8")) as {
+    version?: unknown;
+  };
+
+  if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+    throw new Error("Could not determine @andreprado/agentkit package version for the generated capsule.");
+  }
+
+  return packageJson.version;
+}
+
+async function loadDefaultSkillFiles(): Promise<TemplateFile[]> {
+  const sourceRoot = join(moduleDir, "templates", "skills");
+  const sourceFiles = await listFiles(sourceRoot);
+
+  return Promise.all(
+    sourceFiles.map(async (sourcePath) => ({
+      path: join("skills", relative(sourceRoot, sourcePath)).replaceAll("\\", "/"),
+      contents: await readFile(sourcePath, "utf8"),
+    })),
+  );
+}
+
+async function listFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const path = join(directory, entry.name);
+
+      if (entry.isDirectory()) {
+        return listFiles(path);
+      }
+
+      return entry.isFile() ? [path] : [];
+    }),
+  );
+
+  return files.flat().sort();
+}
+
+async function directoryExists(path: string): Promise<boolean> {
+  try {
+    const result = await stat(path);
+    return result.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}