@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/runtime/spec.ts

@@ -0,0 +1,152 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+
+import { findAgentCapsuleRoot } from "./config";
+import { AgentKitError } from "./errors";
+
+export type AgentSpecInitResult = {
+  root: string;
+  file: string;
+  created: boolean;
+};
+
+const REQUIRED_SPEC_HEADINGS = [
+  "Objective",
+  "Primary Flows",
+  "Required Data",
+  "Tools And Integrations",
+  "Knowledge",
+  "Handoff And Escalation",
+  "Limits",
+  "Acceptance Criteria",
+] as const;
+
+export async function initializeAgentSpec(
+  cwd: string,
+  input: {
+    brief: string;
+    out?: string;
+    force?: boolean;
+  },
+): Promise<AgentSpecInitResult> {
+  const root = await findAgentCapsuleRoot(cwd);
+  const brief = input.brief.trim();
+
+  if (!brief) {
+    throw new AgentKitError("validation_error", "agentkit spec init requires a non-empty --brief value.");
+  }
+
+  const file = resolve(root, input.out ?? "AGENT_SPEC.md");
+
+  if (!input.force && await pathExists(file)) {
+    throw new AgentKitError(
+      "validation_error",
+      `${relative(root, file)} already exists. Update it directly, re-run with --force, or choose --out <path>.`,
+    );
+  }
+
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, renderAgentSpec(brief));
+
+  return {
+    root,
+    file,
+    created: true,
+  };
+}
+
+export async function checkAgentSpec(cwd: string, fileName = "AGENT_SPEC.md"): Promise<{
+  root: string;
+  file: string;
+  ok: boolean;
+  missingHeadings: string[];
+}> {
+  const root = await findAgentCapsuleRoot(cwd);
+  const file = resolve(root, fileName);
+  let source: string;
+
+  try {
+    source = await readFile(file, "utf8");
+  } catch (error) {
+    throw new AgentKitError(
+      "validation_error",
+      `${relative(root, file)} was not found. Run agentkit spec init --brief "<owner request>" after the owner gives the agent idea.`,
+      { cause: error },
+    );
+  }
+
+  const missingHeadings = REQUIRED_SPEC_HEADINGS.filter((heading) => !source.includes(`## ${heading}`));
+
+  return {
+    root,
+    file,
+    ok: missingHeadings.length === 0,
+    missingHeadings,
+  };
+}
+
+function renderAgentSpec(brief: string): string {
+  return `# Agent Spec
+
+## Owner Request
+
+${brief}
+
+## Objective
+
+Define the agent's job in one or two concrete sentences before editing prompts or tools.
+
+## Primary Flows
+
+- Flow 1:
+- Flow 2:
+- Flow 3:
+
+## Required Data
+
+- User data to collect:
+- Business data to read:
+- Records to create or update:
+
+## Tools And Integrations
+
+- Tools to add:
+- External systems:
+- Secrets needed:
+
+## Knowledge
+
+- Documents, FAQs, catalogs, CSVs, or policies to add:
+- Sync source, if any:
+
+## Handoff And Escalation
+
+- When the agent should stop and hand off:
+- What information the handoff must include:
+
+## Limits
+
+- The agent must not:
+- Safety, compliance, or authorization boundaries:
+
+## Acceptance Criteria
+
+- [ ] Prompt updated for the domain and boundaries.
+- [ ] Tools added for actions, live data, or durable writes.
+- [ ] Knowledge or seed data added when the agent needs catalog facts.
+- [ ] Multi-turn eval covers the main user flow.
+- [ ] Direct tool checks pass for every new tool.
+- [ ] \`npm run typecheck\` passes.
+- [ ] \`npm run agentkit -- inspect\` passes.
+- [ ] \`npm run eval\` passes.
+`;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/runtime/sync.ts

@@ -0,0 +1,144 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { SyncContext } from "../index";
+import { findAgentCapsuleRoot, loadAgentCapsule } from "./config";
+import { createLocalDatabaseRunner, openPreparedCapsuleStore } from "./database";
+import { loadCapsuleEnv } from "./env";
+import { AgentKitError } from "./errors";
+
+export type SyncRunResult = {
+  root: string;
+  file: string;
+  output: unknown;
+};
+
+export type SyncInitResult = {
+  root: string;
+  files: string[];
+};
+
+type SyncModule = {
+  default?: unknown;
+  sync?: unknown;
+};
+
+export async function runCapsuleSync(cwd: string, input: { file?: string } = {}): Promise<SyncRunResult> {
+  const capsule = await loadAgentCapsule(cwd);
+  const file = resolve(capsule.root, input.file ?? "sync.ts");
+  const sync = await loadSyncFunction(file);
+  const env = await loadCapsuleEnv(capsule.root);
+  const prepared = await openPreparedCapsuleStore(capsule);
+
+  try {
+    const db = createLocalDatabaseRunner(prepared.store);
+    const context: SyncContext = {
+      env,
+      database: db,
+      db,
+      runtime: {
+        environment: "local",
+        invocation: "sync",
+        target: "bun",
+        database: "sqlite",
+      },
+    };
+    const output = await sync(context);
+
+    return {
+      root: capsule.root,
+      file,
+      output: output ?? { ok: true },
+    };
+  } finally {
+    prepared.store.close();
+  }
+}
+
+export async function initializeSyncScaffold(cwd: string, input: { force?: boolean } = {}): Promise<SyncInitResult> {
+  const root = await findAgentCapsuleRoot(cwd);
+  const files = [
+    {
+      path: "sync.ts",
+      contents: `import type { SyncContext } from "@andreprado/agentkit";
+
+export default async function sync(ctx: SyncContext) {
+  // Replace this with catalog/API import logic. Use ctx.db for durable writes.
+  await ctx.db.execute(
+    "INSERT OR IGNORE INTO agent_notes (id, content) VALUES (?, ?)",
+    ["seed-note", "Created by sync.ts"],
+  );
+
+  return {
+    ok: true,
+    recordsImported: 1,
+  };
+}
+`,
+    },
+    {
+      path: "seed.sql",
+      contents: `INSERT OR IGNORE INTO agent_notes (id, content)
+VALUES ('seed-note', 'Created by seed.sql');
+`,
+    },
+    {
+      path: "migrations/0001_initial.sql",
+      contents: `CREATE TABLE IF NOT EXISTS agent_notes (
+  id TEXT PRIMARY KEY,
+  content TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+`,
+    },
+  ];
+  const written: string[] = [];
+
+  for (const file of files) {
+    const absolutePath = resolve(root, file.path);
+
+    if (!input.force && await pathExists(absolutePath)) {
+      continue;
+    }
+
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, file.contents);
+    written.push(file.path);
+  }
+
+  return { root, files: written };
+}
+
+async function loadSyncFunction(file: string): Promise<(context: SyncContext) => Promise<unknown> | unknown> {
+  let module: SyncModule;
+
+  try {
+    const url = pathToFileURL(file);
+    url.searchParams.set("t", String(Date.now()));
+    module = (await import(url.href)) as SyncModule;
+  } catch (error) {
+    throw new AgentKitError(
+      "validation_error",
+      `Could not load sync file at ${relative(process.cwd(), file)}. Run agentkit sync init or pass --file <path>.`,
+      { cause: error },
+    );
+  }
+
+  const sync = module.default ?? module.sync;
+
+  if (typeof sync !== "function") {
+    throw new AgentKitError("validation_error", `${relative(process.cwd(), file)} must export a default sync function.`);
+  }
+
+  return sync as (context: SyncContext) => Promise<unknown> | unknown;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}