@andreprado/agentkit 0.1.0-alpha.6 → 0.1.0-alpha.8

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;
+  }
+}

package/src/runtime/targets/cloudflare/build.ts

@@ -751,6 +751,10 @@ export default {
       return Response.json({ status: "ok", agent: manifest.name });
     }
 
+    if (isHostedChannelWebhookPath(url.pathname)) {
+      return forwardHostedChannelWebhook(request, env, url);
+    }
+
     if (request.method === "POST" && (url.pathname === "/chat" || url.pathname === "/v1/chat")) {
       return handleChat(request, env);
     }
@@ -775,6 +779,47 @@ export default {
   },
 };
 
+function isHostedChannelWebhookPath(pathname) {
+  return (
+    /^\\/channels\\/[^/]+\\/(?:website|telegram)\\/webhook$/.test(pathname) ||
+    /^\\/channels\\/[^/]+\\/whatsapp\\/(?:zapster|meta)\\/webhook$/.test(pathname)
+  );
+}
+
+async function forwardHostedChannelWebhook(request, env, url) {
+  if (!env.AGENTKIT_CLOUD_API_URL) {
+    return Response.json(
+      {
+        error: {
+          code: "channel_webhook_proxy_not_configured",
+          message: "Hosted channel webhooks require AGENTKIT_CLOUD_API_URL on the deployed Worker.",
+        },
+      },
+      { status: 501 },
+    );
+  }
+
+  const target = new URL(\`\${url.pathname}\${url.search}\`, env.AGENTKIT_CLOUD_API_URL);
+  const headers = new Headers(request.headers);
+  headers.delete("host");
+  headers.delete("content-length");
+
+  if (env.AGENTKIT_DEPLOY_ID) {
+    headers.set("X-AgentKit-Deploy-ID", env.AGENTKIT_DEPLOY_ID);
+  }
+
+  if (env.AGENTKIT_RUNTIME_GATE_TOKEN) {
+    headers.set("X-AgentKit-Runtime-Gate", env.AGENTKIT_RUNTIME_GATE_TOKEN);
+  }
+
+  return fetch(target.href, {
+    method: request.method,
+    headers,
+    body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
+    redirect: "manual",
+  });
+}
+
 async function handleTursoHealth(request, env) {
   const auth = authorizeAdmin(request, env);
 

package/src/runtime/tools.ts

@@ -1,4 +1,4 @@
-import type { AgentTool, JsonSchema, ToolContext, ToolRuntimeContext } from "../index";
+import type { AgentTool, JsonSchema, ToolContext, ToolRenderResult, ToolRuntimeContext } from "../index";
 import type { SqliteAgentKitStore } from "../storage/sqlite";
 import { createLocalDatabaseRunner } from "./database";
 import { AgentKitError } from "./errors";
@@ -14,6 +14,7 @@ export type ToolCallResult = {
   visibility: "user" | "internal";
   input: unknown;
   output: unknown;
+  rendered?: ToolRenderResult;
 };
 
 export type ToolRuntime = {
@@ -97,10 +98,13 @@ async function executeToolCall(
       validateSchema(output, tool.outputSchema, `tool "${tool.name}" output`);
     }
 
+    const rendered = renderToolOutput(tool, input, output, options.runtime);
+
     options.store.completeToolCall({
       toolCallId: toolCall.id,
       status: "completed",
       output,
+      rendered,
       secretValues,
     });
 
@@ -110,6 +114,7 @@ async function executeToolCall(
       visibility: tool.visibility ?? "user",
       input,
       output,
+      ...(rendered ? { rendered } : {}),
     };
   } catch (error) {
     const secretValues = collectConfiguredSecretValues(tool, options.env ?? process.env);
@@ -125,6 +130,121 @@ async function executeToolCall(
   }
 }
 
+function renderToolOutput(
+  tool: AgentTool,
+  input: unknown,
+  output: unknown,
+  runtime: ToolRuntimeContext,
+): ToolRenderResult | undefined {
+  if (!tool.render) {
+    return undefined;
+  }
+
+  const rendered = tool.render(output, {
+    input,
+    runtime,
+  });
+
+  if (typeof rendered === "string") {
+    return { text: rendered };
+  }
+
+  if (!isRecord(rendered) || typeof rendered.text !== "string" || rendered.text.trim().length === 0) {
+    throw new AgentKitError("tool_validation_error", `tool "${tool.name}" render must return a non-empty text string.`);
+  }
+
+  if (rendered.blocks !== undefined) {
+    if (!Array.isArray(rendered.blocks)) {
+      throw new AgentKitError("tool_validation_error", `tool "${tool.name}" render.blocks must be an array when provided.`);
+    }
+
+    for (const [index, block] of rendered.blocks.entries()) {
+      validateRenderBlock(block, `tool "${tool.name}" render.blocks[${index}]`);
+    }
+  }
+
+  return {
+    text: rendered.text,
+    ...(rendered.blocks ? { blocks: rendered.blocks } : {}),
+  };
+}
+
+function validateRenderBlock(block: unknown, label: string): void {
+  if (!isRecord(block)) {
+    throw new AgentKitError("tool_validation_error", `${label} must be an object.`);
+  }
+
+  if (block.type === "text") {
+    if (typeof block.text !== "string" || block.text.trim().length === 0) {
+      throw new AgentKitError("tool_validation_error", `${label}.text must be a non-empty string.`);
+    }
+    return;
+  }
+
+  if (block.type === "card") {
+    if (typeof block.title !== "string" || block.title.trim().length === 0) {
+      throw new AgentKitError("tool_validation_error", `${label}.title must be a non-empty string.`);
+    }
+
+    validateOptionalString(block.subtitle, `${label}.subtitle`);
+    validateRenderFields(block.fields, `${label}.fields`);
+    validateRenderActions(block.actions, `${label}.actions`);
+    return;
+  }
+
+  throw new AgentKitError("tool_validation_error", `${label}.type must be "text" or "card".`);
+}
+
+function validateRenderFields(value: unknown, label: string): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new AgentKitError("tool_validation_error", `${label} must be an array when provided.`);
+  }
+
+  for (const [index, field] of value.entries()) {
+    if (!isRecord(field)) {
+      throw new AgentKitError("tool_validation_error", `${label}[${index}] must be an object.`);
+    }
+
+    validateRequiredString(field.label, `${label}[${index}].label`);
+    validateRequiredString(field.value, `${label}[${index}].value`);
+  }
+}
+
+function validateRenderActions(value: unknown, label: string): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new AgentKitError("tool_validation_error", `${label} must be an array when provided.`);
+  }
+
+  for (const [index, action] of value.entries()) {
+    if (!isRecord(action)) {
+      throw new AgentKitError("tool_validation_error", `${label}[${index}] must be an object.`);
+    }
+
+    validateRequiredString(action.label, `${label}[${index}].label`);
+    validateOptionalString(action.href, `${label}[${index}].href`);
+  }
+}
+
+function validateRequiredString(value: unknown, label: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new AgentKitError("tool_validation_error", `${label} must be a non-empty string.`);
+  }
+}
+
+function validateOptionalString(value: unknown, label: string): void {
+  if (value !== undefined && typeof value !== "string") {
+    throw new AgentKitError("tool_validation_error", `${label} must be a string when provided.`);
+  }
+}
+
 function resolveToolSecrets(
   tool: AgentTool,
   env: Record<string, string | undefined>,

package/src/runtime/traces.ts

@@ -0,0 +1,41 @@
+import type { ConversationRecord, StoredRun, StoredToolCall } from "../storage/sqlite";
+import { openCapsuleStore } from "../storage/sqlite";
+import { loadAgentCapsule } from "./config";
+import { AgentKitError } from "./errors";
+
+export type ConversationTrace = ConversationRecord & {
+  runs: ConversationTraceRun[];
+};
+
+export type ConversationTraceRun = StoredRun & {
+  toolCalls: StoredToolCall[];
+};
+
+export async function getConversationTraceFromCwd(cwd: string, conversationId: string): Promise<ConversationTrace> {
+  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.`);
+    }
+
+    const runs = store.listRunsForConversation(conversation.id).map((run) => ({
+      ...run,
+      toolCalls: store.listToolCallsForRun(run.id),
+    }));
+
+    return {
+      ...conversation,
+      runs,
+    };
+  } finally {
+    store.close();
+  }
+}