@andreprado/agentkit 0.1.0-alpha.5 → 0.1.0-alpha.7

package/src/cli/help.ts

@@ -21,9 +21,14 @@ Start:
   agentkit inspect
 
 Build:
+  agentkit knowledge add <path>
+  agentkit knowledge search <query>
+  agentkit spec init --brief <text>
+  agentkit sync run
   agentkit tool <name> [--input <path-or-json>]
   agentkit db migrate
   agentkit eval run
+  agentkit eval from-conversation <id>
   agentkit conversations list
 
 Deploy:
@@ -53,13 +58,23 @@ Usage:
   agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
   agentkit chat --message <text> [--conversation-id <id>]
   agentkit tool <name> [--input <path-or-json>]
+  agentkit knowledge add <path-or-url>
+  agentkit knowledge sync
+  agentkit knowledge inspect
+  agentkit knowledge search <query> [--top-k <number>]
+  agentkit spec init --brief <text> [--out <path>] [--force]
+  agentkit spec check [--file <path>]
+  agentkit sync init [--force]
+  agentkit sync run [--file <path>]
   agentkit db migrate
   agentkit db reset --yes
   agentkit db shell
   agentkit db seed [--file <path>]
   agentkit eval run
+  agentkit eval from-conversation <conversation-id> [--out <path>] [--force]
   agentkit conversations list
   agentkit conversations show <conversation-id>
+  agentkit conversations trace <conversation-id>
   agentkit channels list
   agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
   agentkit channels setup <name> [--apply] [--api <url>]
@@ -106,9 +121,12 @@ Commands:
   chat-ui         Run a local chat UI, optionally pointed at a hosted deploy
   chat            Send one message to the local Agent Capsule
   tool            Run one registered tool directly
+  knowledge       Add, sync, inspect, and search local Knowledge sources
+  spec            Create or check the agent implementation contract from the owner brief
+  sync            Run or scaffold catalog/data synchronization
   db              Manage the local SQLite database
-  eval            Run local eval files
-  conversations   List and inspect stored local conversations
+  eval            Run local eval files or create one from a conversation
+  conversations   List, inspect, and trace stored local conversations
   channels        Manage hosted channel resources
   inspect         Print machine-readable Agent Capsule state
   build           Build a hosted deploy artifact
@@ -142,6 +160,12 @@ export function renderCommandHelp(command: string): string {
     "chat-ui": "agentkit chat-ui --deploy [--port <number>] [--token-file <path>]",
     chat: 'agentkit chat --message "hello" [--conversation-id <id>]',
     tool: "agentkit tool <name> [--input <path-or-json>]",
+    knowledge: "agentkit knowledge add <path-or-url> | sync | inspect | search <query> [--top-k <number>]",
+    spec: 'agentkit spec init --brief "owner request" | agentkit spec check',
+    sync: "agentkit sync init [--force] | agentkit sync run [--file <path>]",
+    eval: "agentkit eval run | agentkit eval from-conversation <conversation-id> [--out <path>] [--force]",
+    conversations:
+      "agentkit conversations list | agentkit conversations show <conversation-id> | agentkit conversations trace <conversation-id>",
     deploy:
       'agentkit deploy [--smoke "hello"] | agentkit deploy smoke [--message "hello"] | agentkit deploy doctor | status | pause | resume',
     secret:

package/src/cli/index.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 
@@ -8,6 +9,7 @@ import { findAgentCapsuleRoot, loadAgentCapsule } from "../runtime/config";
 import { readLocalDeployStateIfExists, type LocalDeployState } from "../runtime/core/deploy-state";
 import { resolveBuildTarget, resolveDeployTarget } from "../runtime/core/targets";
 import { getConversationFromCwd, listConversationsFromCwd } from "../runtime/conversations";
+import { getConversationTraceFromCwd } from "../runtime/traces";
 import { runAgentMessageFromCwd } from "../runtime/chat";
 import { deployBuildToAgentKitCloud, writeLocalDeployState } from "../runtime/deploy";
 import {
@@ -16,9 +18,11 @@ import {
   resetLocalDatabase,
   seedLocalDatabase,
 } from "../runtime/db-commands";
-import { runEvalsFromCwd } from "../runtime/evals";
+import { runEvalsFromCwd, writeEvalFromConversation } from "../runtime/evals";
 import { findAgentKitDocs } from "../runtime/docs";
 import { listCapsuleEnv, setCapsuleEnv, unsetCapsuleEnv } from "../runtime/env";
+import { checkAgentSpec, initializeAgentSpec } from "../runtime/spec";
+import { initializeSyncScaffold, runCapsuleSync } from "../runtime/sync";
 import { runToolFromCwd } from "../runtime/tool-runner";
 import { startAgentDevServer } from "../runtime/dev-server";
 import { inspectAgentCapsule } from "../runtime/inspect";
@@ -61,6 +65,7 @@ import {
 import { renderCommandHelp, renderCommandReference, renderHelp } from "./help";
 import { runInheritedCommand, waitForShutdown } from "./process";
 import { handleChannelsCommand } from "./commands/channels";
+import { handleKnowledgeCommand } from "./commands/knowledge";
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
@@ -118,6 +123,7 @@ async function main() {
       console.log("  npm install");
     }
     console.log("  open this folder in Codex or Claude Code");
+    console.log("  coding agents start at skills/agentkit-capsule/SKILL.md");
     console.log('  ask: "Develop an appointment and intake agent for an ophthalmology office"');
     console.log('  npm run chat -- --message "hello"');
     console.log("  npm run dev");
@@ -144,6 +150,7 @@ async function main() {
     console.log(`API:       ${devServer.urls.api}`);
     console.log(`Inspect:   ${devServer.urls.inspect}`);
     console.log(`Storage:   ${devServer.storage ?? "managed"}`);
+    console.log("Reload:    prompts/config reload per request; restart after changing tool modules or dependencies");
     await waitForShutdown(devServer.stop);
     return;
   }
@@ -221,6 +228,8 @@ async function main() {
       const result = await migrateLocalDatabase(process.cwd());
       console.log("Local database migrated");
       console.log(`Database: ${result.databasePath}`);
+      console.log(`Migrations: ${result.migrationsPath ?? "none"}`);
+      console.log(`Applied:    ${result.migrationsApplied.length > 0 ? result.migrationsApplied.join(", ") : "none"}`);
       console.log(`Schema:   ${result.schemaPath ?? "none"}`);
       return;
     }
@@ -234,6 +243,8 @@ async function main() {
       console.log("Local database reset");
       console.log(`Deleted:  ${result.resetPath}`);
       console.log(`Database: ${result.databasePath}`);
+      console.log(`Migrations: ${result.migrationsPath ?? "none"}`);
+      console.log(`Applied:    ${result.migrationsApplied.length > 0 ? result.migrationsApplied.join(", ") : "none"}`);
       console.log(`Schema:   ${result.schemaPath ?? "none"}`);
       return;
     }
@@ -256,6 +267,8 @@ async function main() {
       const result = await seedLocalDatabase(process.cwd(), seedFile);
       console.log("Local database seeded");
       console.log(`Database: ${result.databasePath}`);
+      console.log(`Migrations: ${result.migrationsPath ?? "none"}`);
+      console.log(`Applied:    ${result.migrationsApplied.length > 0 ? result.migrationsApplied.join(", ") : "none"}`);
       console.log(`Schema:   ${result.schemaPath ?? "none"}`);
       console.log(`Seed:     ${result.seedPath}`);
       return;
@@ -265,10 +278,39 @@ async function main() {
   }
 
   if (args.command === "eval") {
-    const [subcommand] = args.positional;
+    const [subcommand, conversationId] = args.positional;
+
+    if (subcommand === "from-conversation") {
+      if (!conversationId) {
+        throw new Error("Missing conversation id. Usage: agentkit eval from-conversation <conversation-id> [--out <path>] [--force]");
+      }
+
+      const out = parseOptionalStringFlag(
+        args.flags.out,
+        "out",
+        "agentkit eval from-conversation <conversation-id> --out <path>",
+      );
+      const name = parseOptionalStringFlag(
+        args.flags.name,
+        "name",
+        "agentkit eval from-conversation <conversation-id> --name <name>",
+      );
+      const result = await writeEvalFromConversation(process.cwd(), {
+        conversationId,
+        out,
+        name,
+        force: args.flags.force === true,
+      });
+
+      console.log("Eval created from conversation");
+      console.log(`Conversation: ${result.conversationId}`);
+      console.log(`File:         ${relativePath(result.root, result.file)}`);
+      console.log(`Turns:        ${result.turns}`);
+      return;
+    }
 
     if (subcommand !== "run") {
-      throw new Error("Usage: agentkit eval run");
+      throw new Error("Usage: agentkit eval run | agentkit eval from-conversation <conversation-id> [--out <path>] [--force]");
     }
 
     const summary = await runEvalsFromCwd(process.cwd());
@@ -337,7 +379,93 @@ async function main() {
       return;
     }
 
-    throw new Error("Usage: agentkit conversations list | agentkit conversations show <conversation-id>");
+    if (subcommand === "trace") {
+      if (!conversationId) {
+        throw new Error("Missing conversation id. Usage: agentkit conversations trace <conversation-id>");
+      }
+
+      const trace = await getConversationTraceFromCwd(process.cwd(), conversationId);
+      console.log(JSON.stringify(trace, null, 2));
+      return;
+    }
+
+    throw new Error("Usage: agentkit conversations list | agentkit conversations show <conversation-id> | agentkit conversations trace <conversation-id>");
+  }
+
+  if (args.command === "knowledge") {
+    await handleKnowledgeCommand(args);
+    return;
+  }
+
+  if (args.command === "sync") {
+    const [subcommand] = args.positional;
+
+    if (subcommand === "init") {
+      const result = await initializeSyncScaffold(process.cwd(), {
+        force: args.flags.force === true,
+      });
+
+      console.log("Sync scaffold ready");
+      if (result.files.length === 0) {
+        console.log("Files: none written; existing files kept");
+      } else {
+        console.log(`Files: ${result.files.join(", ")}`);
+      }
+      return;
+    }
+
+    if (subcommand === "run") {
+      const file = parseOptionalStringFlag(args.flags.file, "file", "agentkit sync run --file <path>");
+      const result = await runCapsuleSync(process.cwd(), { file });
+
+      console.log("Sync completed");
+      console.log(`File:   ${relativePath(result.root, result.file)}`);
+      console.log(`Output: ${JSON.stringify(result.output)}`);
+      return;
+    }
+
+    throw new Error("Usage: agentkit sync init [--force] | agentkit sync run [--file <path>]");
+  }
+
+  if (args.command === "spec") {
+    const [subcommand] = args.positional;
+
+    if (subcommand === "init") {
+      const brief = parseRequiredStringFlag(
+        args.flags.brief,
+        "brief",
+        'agentkit spec init --brief "agent for a real estate brokerage"',
+      );
+      const out = parseOptionalStringFlag(args.flags.out, "out", "agentkit spec init --out <path>");
+      const result = await initializeAgentSpec(process.cwd(), {
+        brief,
+        out,
+        force: args.flags.force === true,
+      });
+
+      console.log("Agent spec created");
+      console.log(`File: ${relativePath(result.root, result.file)}`);
+      return;
+    }
+
+    if (subcommand === "check") {
+      const file = parseOptionalStringFlag(args.flags.file, "file", "agentkit spec check --file <path>");
+      const result = await checkAgentSpec(process.cwd(), file);
+
+      if (result.ok) {
+        console.log(`Agent spec ok: ${relativePath(result.root, result.file)}`);
+        return;
+      }
+
+      console.log(`Agent spec incomplete: ${relativePath(result.root, result.file)}`);
+      for (const heading of result.missingHeadings) {
+        console.log(`  - missing ## ${heading}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    throw new Error('Usage: agentkit spec init --brief "<owner request>" [--out <path>] [--force] | agentkit spec check [--file <path>]');
   }
 
   if (args.command === "inspect") {
@@ -718,15 +846,17 @@ async function main() {
 
     const root = await findAgentCapsuleRoot(process.cwd());
     const docs = findAgentKitDocs();
-    console.log(renderHandoffPrompt({ target, root, docsFull: docs.llmsFull, goal: goalParts.join(" ").trim() }));
+    console.log(renderHandoffPrompt({ target, root, docsLlms: docs.llms, goal: goalParts.join(" ").trim() }));
     return;
   }
 
   throw new Error(`Unknown command: ${args.command}`);
 }
 
-function renderHandoffPrompt(input: { target: string; root: string; docsFull: string; goal: string }): string {
+function renderHandoffPrompt(input: { target: string; root: string; docsLlms: string; goal: string }): string {
   const agentName = input.target === "claude" ? "Claude Code" : "Codex";
+  const skillRouter = join(input.root, "skills/agentkit-capsule/SKILL.md");
+  const skillLine = existsSync(skillRouter) ? `- ${skillRouter}\n` : "";
   const goal = input.goal
     ? `Owner request:
 ${input.goal}`
@@ -740,12 +870,14 @@ ${input.root}
 Read these files first:
 
 - ${join(input.root, "AGENTKIT.md")}
-- ${input.docsFull}
+${skillLine}- ${input.docsLlms}
 
 ${goal}
 
 Rules:
-- Follow the AgentKit contract in llms-full.txt.
+- Start with the AgentKit capsule skill when it exists.
+- Use llms.txt as the docs router.
+- Read llms-full.txt only when a skill or ambiguous framework behavior requires the complete contract.
 - Treat the owner's request as the brief.
 - Build or update the agent inside this capsule as far as you can without asking for obvious restatements.
 - Do not wait for a wizard or recipe; implement directly in the capsule files.

package/src/cloud/artifact.ts

@@ -1,10 +1,15 @@
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+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"),
@@ -40,9 +45,95 @@ export async function createHostedDeployArtifact(build: AgentBuildResult): Promi
     };
   }
 
+  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/contracts.ts

@@ -16,6 +16,17 @@ export type HostedDeployArtifact = {
     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 = {
@@ -37,6 +48,11 @@ export type CreateDeployResponse = {
       mode: string;
       private_token?: string;
     };
+    knowledge?: {
+      enabled: boolean;
+      sources: number;
+      chunks: number;
+    };
   };
 };
 

package/src/create-project.ts

@@ -1,10 +1,10 @@
 import { execFile } from "node:child_process";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+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 } from "./templates";
+import { getTemplate, type TemplateFile } from "./templates";
 
 const execFileAsync = promisify(execFile);
 const moduleDir = dirname(fileURLToPath(import.meta.url));
@@ -27,9 +27,12 @@ export async function createProject(options: CreateProjectOptions): Promise<Crea
 
   const template = getTemplate(options.template);
   const projectPath = target.path;
-  const files = template.files(target.name, {
-    agentkitDependency: await resolveAgentKitDependency(),
-  });
+  const files = [
+    ...template.files(target.name, {
+      agentkitDependency: await resolveAgentKitDependency(),
+    }),
+    ...(await loadDefaultSkillFiles()),
+  ];
 
   if (target.currentDirectory) {
     await ensureNoFileCollisions(projectPath, files.map((file) => file.path));
@@ -126,6 +129,35 @@ async function resolveAgentKitDependency(): Promise<string> {
   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);