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

package/README.md

@@ -37,9 +37,13 @@ agentkit tool <name> [--input <path-or-json>]
 agentkit knowledge add <path-or-url>
 agentkit knowledge sync
 agentkit knowledge search <query> [--top-k <number>]
+agentkit spec init --brief <text>
 agentkit db migrate
+agentkit sync run
 agentkit eval run
+agentkit eval from-conversation <conversation-id>
 agentkit conversations list
+agentkit conversations trace <conversation-id>
 ```
 
 Knowledge indexes local `.md`, `.txt`, and `.csv` sources into the capsule database and registers the internal `agentkit_search_knowledge` chat tool when `knowledge` is configured in `agentkit.config.ts`. `agentkit dev` and `agentkit chat` sync configured sources automatically; when embeddings are configured, local semantic search uses a libSQL vector sidecar. Hosted Cloudflare deploys package configured local Knowledge sources and sync them into the project Turso database automatically during `agentkit deploy`; when embeddings are configured, the deploy also creates and populates the hosted Turso vector index.

package/docs/guides/connect-telegram.md

@@ -76,6 +76,8 @@ telegramChannel({
 - `secret_token`: `TELEGRAM_WEBHOOK_SECRET`;
 - `allowed_updates`: `["message"]`.
 
+Against AgentKit Cloud, `--apply` runs through the Cloud API and uses managed hosted secrets. The legacy local fallback only uses `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET` from the shell when the Cloud API does not expose channel setup.
+
 ## Safety Rules
 
 - Use `--apply` only when real Telegram secrets are present.

package/docs/guides/create-agent.md

@@ -86,6 +86,15 @@ Develop an appointment and intake agent for an ophthalmology office.
 
 The generated `AGENTS.md`, `AGENTKIT.md`, `CLAUDE.md`, and `skills/` pack tell the coding agent which files to edit, which task skill to load, and which verification commands to run. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold, contract, and owner request. The default router is `skills/agentkit-capsule/SKILL.md`; `llms-full.txt` is reserved for complete-contract checks.
 
+After the owner gives the general idea, the coding agent should create or update the implementation contract itself:
+
+```sh
+npm run agentkit -- spec init --brief "Develop an appointment and intake agent for an ophthalmology office."
+npm run agentkit -- spec check
+```
+
+`AGENT_SPEC.md` is an internal working contract for the coding agent. It is not a form the owner must fill before work starts.
+
 Optional shortcut when copying a prompt into another coding agent:
 
 ```sh

package/docs/guides/run-evals.md

@@ -22,6 +22,15 @@ Run evals:
 agentkit eval run
 ```
 
+Create an eval from a stored conversation:
+
+```sh
+agentkit conversations list
+agentkit conversations trace <conversation-id>
+agentkit eval from-conversation <conversation-id>
+agentkit eval run
+```
+
 ## Files Created Or Edited
 
 Create or edit:
@@ -62,7 +71,33 @@ matches_regex
 persisted_tool_call
 ```
 
-`persisted_tool_call` validates the tool call saved in local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `status`, and/or `visibility`.
+Multi-turn conversation evals use `turns`:
+
+```ts
+export default {
+  name: "buyer under budget",
+  turns: [
+    {
+      input: "I want a house up to 600k near Pinheiros.",
+      expect: {
+        persisted_tool_call: {
+          name: "buscar_imoveis",
+          status: "completed",
+          input: { maxPrice: 600000 },
+        },
+      },
+    },
+    {
+      input: "Show me the best two.",
+      expect: {
+        contains: ["Pinheiros", "R$"],
+      },
+    },
+  ],
+};
+```
+
+`persisted_tool_call` validates the tool call saved in local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`.
 
 Use response assertions and persisted tool assertions together when internal operational output must not leak:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "private": false,
   "type": "module",
   "repository": {

package/src/cli/cloud-client.ts

@@ -153,9 +153,13 @@ export async function cloudPost<T>(apiUrl: string, path: string, body: unknown):
   return payload as T;
 }
 
-export function cloudFetch(apiUrl: string, path: string, init: RequestInit = {}): Promise<Response> {
+export async function cloudFetch(apiUrl: string, path: string, init: RequestInit = {}): Promise<Response> {
   const headers = new Headers(init.headers);
-  const apiToken = process.env.AGENTKIT_CLOUD_API_TOKEN;
+  const auth = await readCloudAuth();
+  const apiToken =
+    auth?.source === "file" && !cloudAuthMatchesApiUrl(auth, apiUrl)
+      ? undefined
+      : auth?.token;
 
   if (apiToken && !headers.has("Authorization")) {
     headers.set("Authorization", `Bearer ${apiToken}`);
@@ -167,6 +171,10 @@ export function cloudFetch(apiUrl: string, path: string, init: RequestInit = {})
   });
 }
 
+function cloudAuthMatchesApiUrl(auth: CloudAuthConfig, apiUrl: string): boolean {
+  return parseCloudApiUrl(auth.apiUrl) === parseCloudApiUrl(apiUrl);
+}
+
 export async function cloudApiRequest(apiUrl: string, path: string, init: RequestInit): Promise<unknown> {
   const auth = await readCloudAuth();
   const headers = new Headers(init.headers);

package/src/cli/commands/channels.ts

@@ -99,7 +99,7 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     printChannelStatus(channel);
     if (channel.type === "telegram") {
       if (args.flags.apply) {
-        await applyTelegramWebhook(channel);
+        await applyTelegramWebhook(channel, args.flags.api);
         console.log("Telegram webhook updated.");
       } else {
         console.log(`Setup: call Telegram setWebhook with ${channel.webhook_url}`);
@@ -201,7 +201,23 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
   );
 }
 
-async function applyTelegramWebhook(channel: CloudChannel): Promise<void> {
+async function applyTelegramWebhook(
+  channel: CloudChannel,
+  apiFlag: string | boolean | undefined,
+): Promise<void> {
+  try {
+    await cloudPost(
+      parseCloudApiUrl(apiFlag),
+      `/v1/channels/${encodeURIComponent(channel.id)}/setup`,
+      {},
+    );
+    return;
+  } catch (error) {
+    if (!shouldFallbackToLocalTelegramSetup(error)) {
+      throw error;
+    }
+  }
+
   const botToken = process.env.TELEGRAM_BOT_TOKEN;
   const secretToken = process.env.TELEGRAM_WEBHOOK_SECRET;
 
@@ -232,6 +248,16 @@ async function applyTelegramWebhook(channel: CloudChannel): Promise<void> {
   }
 }
 
+function shouldFallbackToLocalTelegramSetup(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return /Unknown AgentKit Cloud route|does not support channel delivery records yet|does not support channel resources yet/.test(
+    error.message,
+  );
+}
+
 function isTelegramOk(payload: unknown): payload is { ok: true } {
   return Boolean(payload && typeof payload === "object" && "ok" in payload && payload.ok === true);
 }

package/src/cli/deploy-chat-ui.ts

@@ -335,6 +335,13 @@ function renderDeployChatUi(input: { deployUrl: string }): string {
         messages.scrollTop = messages.scrollHeight;
       }
 
+      textarea.addEventListener("keydown", (event) => {
+        if (event.key !== "Enter" || event.shiftKey || event.isComposing) return;
+        event.preventDefault();
+        if (send.disabled) return;
+        form.requestSubmit();
+      });
+
       form.addEventListener("submit", async (event) => {
         event.preventDefault();
         const message = textarea.value.trim();

package/src/cli/help.ts

@@ -23,9 +23,12 @@ Start:
 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:
@@ -59,13 +62,19 @@ Usage:
   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>]
@@ -113,9 +122,11 @@ Commands:
   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
@@ -150,6 +161,11 @@ export function renderCommandHelp(command: string): string {
     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

@@ -9,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 {
@@ -17,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";
@@ -147,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;
   }
@@ -224,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;
     }
@@ -237,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;
     }
@@ -259,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;
@@ -268,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());
@@ -340,7 +379,17 @@ 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") {
@@ -348,6 +397,77 @@ async function main() {
     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") {
     const state = await inspectAgentCapsule(process.cwd());
     console.log(JSON.stringify(state, null, 2));

package/src/index.ts

@@ -105,6 +105,7 @@ export type AgentDatabaseConfig =
   | {
       driver: "turso";
       schema?: string;
+      migrations?: string;
     };
 
 export type AgentFilesConfig =
@@ -178,9 +179,42 @@ export type DatabaseRunner = {
   batch(statements: DatabaseStatement[]): Promise<DatabaseResult[]>;
 };
 
+export type ToolRenderField = {
+  label: string;
+  value: string;
+};
+
+export type ToolRenderAction = {
+  label: string;
+  href?: string;
+};
+
+export type ToolRenderBlock =
+  | {
+      type: "text";
+      text: string;
+    }
+  | {
+      type: "card";
+      title: string;
+      subtitle?: string;
+      fields?: ToolRenderField[];
+      actions?: ToolRenderAction[];
+    };
+
+export type ToolRenderResult = {
+  text: string;
+  blocks?: ToolRenderBlock[];
+};
+
+export type ToolRenderContext<Input = unknown> = {
+  input: Input;
+  runtime: ToolRuntimeContext;
+};
+
 export type ToolRuntimeContext = {
   environment: "local" | "hosted" | "eval" | "test";
-  invocation: "chat" | "tool" | "dev" | "channel" | "eval";
+  invocation: "chat" | "tool" | "dev" | "channel" | "eval" | "sync";
   target: "bun" | "cloudflare";
   database: "sqlite" | "turso" | "none";
 };
@@ -196,6 +230,13 @@ export type ToolContext = {
   };
 };
 
+export type SyncContext = {
+  env: Record<string, string | undefined>;
+  database: DatabaseRunner;
+  db: DatabaseRunner;
+  runtime: ToolRuntimeContext;
+};
+
 export type AgentTool<Input = unknown, Output = unknown> = {
   name: string;
   description: string;
@@ -206,6 +247,7 @@ export type AgentTool<Input = unknown, Output = unknown> = {
   permissions?: string[];
   timeoutMs?: number;
   execute(input: Input, ctx: ToolContext): Promise<Output> | Output;
+  render?(output: Output, ctx: ToolRenderContext<Input>): string | ToolRenderResult;
 };
 
 export type AgentConfig = {
@@ -338,6 +380,7 @@ export { loadAgentCapsule, findAgentCapsuleRoot } from "./runtime/config";
 export { runAgentMessage, runAgentMessageFromCwd } from "./runtime/chat";
 export { listConversationsFromCwd, getConversationFromCwd } from "./runtime/conversations";
 export { runEvalsFromCwd } from "./runtime/evals";
+export { getConversationTraceFromCwd } from "./runtime/traces";
 export { runToolFromCwd } from "./runtime/tool-runner";
 export { startAgentDevServer } from "./runtime/dev-server";
 export { inspectAgentCapsule } from "./runtime/inspect";

package/src/providers/pi.ts

@@ -97,7 +97,7 @@ async function runPiProvider(input: ProviderRunInput): Promise<ProviderRunResult
         content: [
           {
             type: "text",
-            text: JSON.stringify(result.output),
+            text: result.rendered?.text ?? JSON.stringify(result.output),
           },
         ],
         isError: false,

package/src/providers/test.ts

@@ -29,7 +29,7 @@ export const testProviderAdapter: ProviderAdapter = {
           content:
             toolResult.visibility === "internal"
               ? `Tool ${toolResult.name}: completed`
-              : `Tool ${toolResult.name}: ${JSON.stringify(toolResult.output)}`,
+              : toolResult.rendered?.text ?? `Tool ${toolResult.name}: ${JSON.stringify(toolResult.output)}`,
         },
         raw: {
           toolCalls: [toolResult],

package/src/runtime/config.ts

@@ -561,6 +561,10 @@ function validateDatabaseConfig(value: unknown): void {
   if (value.schema !== undefined && typeof value.schema !== "string") {
     throw invalidConfig("storage.database.schema must be a string when provided.");
   }
+
+  if (value.migrations !== undefined && typeof value.migrations !== "string") {
+    throw invalidConfig("storage.database.migrations must be a string when provided.");
+  }
 }
 
 function validateFilesConfig(value: unknown): void {
@@ -631,6 +635,10 @@ function validateTool(value: unknown, index: number): asserts value is AgentTool
   if (typeof value.execute !== "function") {
     throw invalidConfig(`tools[${index}].execute must be a function.`);
   }
+
+  if (value.render !== undefined && typeof value.render !== "function") {
+    throw invalidConfig(`tools[${index}].render must be a function when provided.`);
+  }
 }
 
 function resolvePath(root: string, path: string): string {