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

package/docs/guides/connect-telegram.md

@@ -51,6 +51,21 @@ export default defineAgent({
 });
 ```
 
+To answer once after a burst of Telegram messages, enable channel buffering:
+
+```ts
+telegramChannel({
+  name: "support-telegram",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 1500,
+    maxWaitMs: 8000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
 ## Setup Behavior
 
 `agentkit channels setup support-telegram` is read-only and prints the webhook URL.
@@ -61,6 +76,8 @@ export default defineAgent({
 - `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/connect-whatsapp-zapster.md

@@ -50,6 +50,22 @@ export default defineAgent({
 });
 ```
 
+To handle clients who send several WhatsApp messages before waiting, enable channel buffering:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
 ## Setup Behavior
 
 `agentkit channels setup support-whatsapp` prints the stable AgentKit webhook URL. Paste it into Zapster webhook settings and configure Zapster to send the same shared secret as `ZAPSTER_WEBHOOK_SECRET`.

package/docs/guides/create-agent.md

@@ -84,7 +84,16 @@ Primary flow:
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The generated `AGENTS.md`, `AGENTKIT.md`, and `CLAUDE.md` tell the coding agent which files to edit 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 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:
 

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/docs/llms-full.txt

@@ -40,6 +40,10 @@ agentkit chat-ui --deploy
 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 db migrate
 agentkit db reset --yes
 agentkit db shell
@@ -144,7 +148,7 @@ npm run agentkit -- handoff codex "Develop an appointment and intake agent for a
 npm run agentkit -- handoff claude "Develop an appointment and intake agent for an ophthalmology office."
 ```
 
-The command prints a ready-to-paste prompt that points the coding agent at `AGENTKIT.md` and the packaged `llms-full.txt` contract.
+The command prints a ready-to-paste prompt that points the coding agent at `AGENTKIT.md`, the repo-local `skills/agentkit-capsule/SKILL.md` router when present, and the packaged `llms.txt` docs router. Load `llms-full.txt` only when a skill or ambiguous framework behavior requires the complete contract.
 
 The generated docs and handoff prompt must make UI testing explicit. For local UI testing, run `npm run dev`, open the printed `Chat:` URL, and tell the owner the exact URL. For hosted UI testing after deploy, run `npm run agentkit -- chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the hosted deploy.
 
@@ -239,6 +243,73 @@ npm run chat -- --message "hello"
 
 If a provider key is missing, the runtime returns `secret_not_found`.
 
+## Knowledge Contract
+
+Knowledge is AgentKit's native retrieval layer for facts the agent should ground in source files. Use it for FAQs, prices, policies, service descriptions, procedures, CSV tables, and reference docs. Do not put secrets, credentials, `.env` contents, or live customer/payment records in Knowledge. Use tools for live or authorization-sensitive data.
+
+Configure Knowledge in `agentkit.config.ts`:
+
+```ts
+knowledge: {
+  sources: [
+    "knowledge/faq.md",
+    { path: "knowledge/prices.csv", title: "Prices" },
+  ],
+  retrieval: {
+    topK: 8,
+    hybrid: false,
+  },
+},
+```
+
+Local Knowledge supports `.md`, `.markdown`, `.txt`, and `.csv` sources inside the Agent Capsule. Markdown chunks follow headings, text chunks follow paragraphs, and CSV chunks preserve row data with headers.
+
+Embeddings are configured separately from the chat provider. The default provider is `none`, which gives local lexical search without an API key. For OpenAI embeddings:
+
+```ts
+knowledge: {
+  sources: ["knowledge/faq.md"],
+  embedding: {
+    provider: "openai",
+    model: "text-embedding-3-small",
+    secret: "KNOWLEDGE_OPENAI_API_KEY",
+  },
+  retrieval: {
+    topK: 8,
+    hybrid: true,
+  },
+},
+```
+
+Set the local embedding secret with `agentkit env set KNOWLEDGE_OPENAI_API_KEY --stdin`. Do not commit the value.
+
+Knowledge commands:
+
+```sh
+agentkit knowledge add knowledge/faq.md
+agentkit knowledge sync
+agentkit knowledge inspect
+agentkit knowledge search "refund policy" --top-k 3
+```
+
+`knowledge add` indexes one local path. `knowledge sync` indexes all configured `knowledge.sources` and skips unchanged files by content hash. `agentkit dev` and `agentkit chat` also sync configured Knowledge automatically before local runs. `knowledge inspect` lists indexed sources and chunk counts. `knowledge search` validates retrieval before relying on the agent. When embeddings are configured locally, AgentKit stores canonical chunks in `.agentkit/agentkit.db`, rebuilds a local libSQL vector sidecar at `.agentkit/agentkit.vectors.db`, uses native `libsql_vector_idx` semantic search, and falls back to stored JSON embeddings if the native vector path is unavailable.
+
+When `knowledge` is configured, AgentKit automatically registers the internal chat tool `agentkit_search_knowledge` and appends a prompt policy. The policy tells the agent to search before answering business-specific factual questions and not to expose raw retrieval JSON, scores, chunk IDs, or tool output objects. With `test/fake`, verify the internal tool directly:
+
+```sh
+agentkit chat --message '{"tool":"agentkit_search_knowledge","input":{"query":"refund policy","topK":1}}'
+```
+
+Expected output:
+
+```txt
+Tool agentkit_search_knowledge: completed
+```
+
+Cloudflare Knowledge deploys require `storage.driver: "agentkit"` and `storage.database.driver: "turso"`. `agentkit deploy doctor` and `agentkit build --target cloudflare` fail clearly when Knowledge is configured without Turso. Cloudflare artifacts include the Knowledge manifest, required embedding secret names, internal Knowledge schema, packaged local source contents, prompt policy, and hosted `agentkit_search_knowledge` runtime. During `agentkit deploy`, AgentKit Cloud applies the Knowledge schema, chunks packaged local sources, creates embeddings when configured, deletes stale hosted sources, and syncs sources, chunks, embedding metadata, FTS rows, and a native Turso `libsql_vector_idx` index into the project Turso database before publishing the Worker. Local `agentkit knowledge add/sync`, `agentkit dev`, and `agentkit chat` index configured Knowledge into local SQLite and the local libSQL vector sidecar; hosted deploy syncs configured local Knowledge sources automatically from the deploy artifact so private source material and embedding secrets do not move into client code. Hosted semantic search uses Turso native vector search when embeddings are configured and falls back to stored JSON embeddings if the native vector path is unavailable.
+
+Full guide: `docs/guides/add-knowledge.md`.
+
 ## Channel Contract
 
 Channels are hosted inbound/outbound conversation transports. They are separate from tools: channels receive user messages, while tools let the agent call external systems.
@@ -272,6 +343,24 @@ Rules:
 - Config stores secret names only, never secret values.
 - AgentKit owns channel webhook URLs, dedupe, identities, queue state, and delivery logs.
 - Do not store channel plumbing in the user's Turso database.
+- Use `buffer.mode: "debounce"` when a channel should coalesce rapid client messages into one agent run.
+- Buffered deliveries show `buffered`, then flush to one `queued` run after `quietWindowMs`, `maxWaitMs`, `maxMessages`, or `maxChars`.
+
+Channel buffer example:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
 
 Useful guides:
 

package/docs/llms.txt

@@ -2,12 +2,13 @@
 
 AgentKit creates and runs Agent Capsules: folders with `agentkit.config.ts`, prompts, tools, evals, local storage, and agent-facing docs.
 
-Read `docs/llms-full.txt` when you need the whole operating contract.
+Read `docs/llms-full.txt` only when you need the whole operating contract.
 
 Task guides:
 
 - Create a capsule: `docs/guides/create-agent.md`
 - Add a TypeScript tool: `docs/guides/add-tool.md`
+- Add Knowledge from local docs/CSVs: `docs/guides/add-knowledge.md`
 - Run or prepare evals: `docs/guides/run-evals.md`
 - Switch from `test/fake` to a real provider: `docs/guides/use-provider.md`
 - Prepare for hosted deploy: `docs/guides/prepare-deploy.md`
@@ -15,11 +16,13 @@ Task guides:
 - Build container artifact: `agentkit build --target container`
 - Generate VPS handoff: `agentkit deploy --target vps --host agent.example.com --dry-run`
 - Add hosted channels: `docs/guides/add-channel.md`
+- Buffer rapid channel messages: `docs/guides/add-channel.md#buffer-bursty-messages`
 - Connect Telegram: `docs/guides/connect-telegram.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Follow channel webhook and delivery-log safety rules: `docs/guides/channel-security.md`
 - Prepare Channels for production: `docs/guides/channels-production-handoff.md`
 - Follow secret, access, and tool safety rules: `docs/guides/security-rules.md`
+- Plan repo-local skills for coding agents: `docs/guides/agentkit-skills-architecture.md`
 
 Current local commands:
 
@@ -33,6 +36,10 @@ agentkit env unset <NAME>
 agentkit handoff codex|claude [goal]
 agentkit chat --message "hello"
 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 eval run
 agentkit conversations list
 agentkit conversations show <conversation-id>
@@ -58,7 +65,7 @@ agentkit dev
 agentkit open
 ```
 
-Generated capsules include `AGENTKIT.md` and `AGENTS.md` so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold and contract.
+Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/` pack so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately without loading the full contract by default. Start with `skills/agentkit-capsule/SKILL.md`, then load the task skill for the current work. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold and contract.
 
 UI testing is part of the handoff. For local UI testing, run `agentkit dev`, open the printed `Chat:` URL, and tell the owner the exact URL. After hosted deploy, run `agentkit chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the deploy.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "private": false,
   "type": "module",
   "repository": {
@@ -35,6 +35,7 @@
   "dependencies": {
     "@earendil-works/pi-ai": "^0.75.5",
     "@earendil-works/pi-coding-agent": "^0.75.5",
+    "@libsql/client": "^0.15.15",
     "esbuild": "^0.28.0",
     "tsx": "^4.22.3",
     "typebox": "^1.1.38"

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

@@ -6,6 +6,7 @@ import { cloudFetch, cloudGet, cloudPost } from "../cloud-client";
 import { parseCloudApiUrl } from "../flags";
 import { loadAgentCapsule } from "../../runtime/config";
 import { readLocalDeployStateIfExists, type LocalDeployState } from "../../runtime/core/deploy-state";
+import type { AgentChannel } from "../../index";
 
 type DeployState = LocalDeployState;
 
@@ -17,6 +18,7 @@ type CloudChannel = {
   status: string;
   webhook_url: string;
   required_secrets: Array<{ name: string; status: string }>;
+  buffer?: AgentChannel["buffer"];
 };
 
 type CloudDelivery = {
@@ -70,11 +72,14 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
 
     const deployState = await readDeployStateRequired(process.cwd());
     const provider = channelProviderForCli(type, args.flags.provider);
+    const localChannel = await readLocalChannelConfig(process.cwd(), type, provider, name);
     const payload = {
       name,
       type,
       provider,
-      secrets: defaultChannelSecretsForCli(type, provider),
+      secrets: localChannel?.secrets ?? defaultChannelSecretsForCli(type, provider),
+      ...(localChannel?.limits ? { limits: channelLimitsForApi(localChannel.limits) } : {}),
+      ...(localChannel?.buffer ? { buffer: localChannel.buffer } : {}),
     };
     const response = await cloudPost<{ channel: CloudChannel }>(
       parseCloudApiUrl(args.flags.api),
@@ -94,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}`);
@@ -196,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;
 
@@ -227,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);
 }
@@ -280,6 +311,15 @@ function printChannelStatus(channel: CloudChannel): void {
   for (const secret of channel.required_secrets) {
     console.log(`  ${secret.name}: ${secret.status}`);
   }
+  if (channel.buffer) {
+    if (channel.buffer.mode === "off") {
+      console.log("Buffer: off");
+    } else {
+      console.log(
+        `Buffer: debounce quiet=${channel.buffer.quietWindowMs}ms max_wait=${channel.buffer.maxWaitMs}ms max_messages=${channel.buffer.maxMessages} max_chars=${channel.buffer.maxChars}`,
+      );
+    }
+  }
 }
 
 async function printChannelDeliverySummary(
@@ -352,6 +392,30 @@ function defaultChannelSecretsForCli(type: string, provider: string): string[] {
   return [];
 }
 
+async function readLocalChannelConfig(
+  cwd: string,
+  type: string,
+  provider: string,
+  name: string,
+): Promise<AgentChannel | null> {
+  const capsule = await loadAgentCapsule(cwd);
+  return (
+    (capsule.config.channels ?? []).find(
+      (channel) => channel.name === name && channel.type === type && channel.provider === provider,
+    ) ?? null
+  );
+}
+
+function channelLimitsForApi(limits: NonNullable<AgentChannel["limits"]>): {
+  messages_per_day?: number;
+  usd_per_day?: number;
+} {
+  return {
+    ...(limits.messagesPerDay ? { messages_per_day: limits.messagesPerDay } : {}),
+    ...(limits.usdPerDay ? { usd_per_day: limits.usdPerDay } : {}),
+  };
+}
+
 async function channelTestBody(
   channel: CloudChannel,
   messageFlag: string | boolean | undefined,

package/src/cli/commands/knowledge.ts

@@ -0,0 +1,136 @@
+import {
+  addKnowledgeSourceFromCwd,
+  listKnowledgeSourcesFromCwd,
+  syncKnowledgeSourcesFromCwd,
+} from "../../runtime/knowledge/ingest";
+import { searchKnowledgeFromCwd } from "../../runtime/knowledge/retrieve";
+import type { ParsedArgs } from "../args";
+
+export async function handleKnowledgeCommand(args: ParsedArgs): Promise<void> {
+  const [subcommand, ...rest] = args.positional;
+
+  if (subcommand === "add") {
+    const [source] = rest;
+
+    if (!source) {
+      throw new Error("Usage: agentkit knowledge add <path-or-url>");
+    }
+
+    const summary = await addKnowledgeSourceFromCwd(process.cwd(), source);
+    printIngestSummary("Knowledge add", summary);
+    return;
+  }
+
+  if (subcommand === "sync") {
+    const summary = await syncKnowledgeSourcesFromCwd(process.cwd());
+    printIngestSummary("Knowledge sync", summary);
+    return;
+  }
+
+  if (subcommand === "inspect") {
+    const result = await listKnowledgeSourcesFromCwd(process.cwd());
+
+    console.log("Knowledge sources");
+    console.log(`Database: ${result.databasePath}`);
+
+    if (result.sources.length === 0) {
+      console.log("No knowledge sources indexed.");
+      return;
+    }
+
+    console.log("");
+    console.log("source\tstatus\tchunks\tupdated_at\ttitle");
+
+    for (const source of result.sources) {
+      console.log(
+        [
+          source.source,
+          source.status,
+          String(source.chunkCount),
+          source.updatedAt,
+          source.title ?? "",
+        ].join("\t"),
+      );
+    }
+
+    return;
+  }
+
+  if (subcommand === "search") {
+    const query = rest.join(" ").trim();
+
+    if (!query) {
+      throw new Error("Usage: agentkit knowledge search <query> [--top-k <number>]");
+    }
+
+    const topK = parseTopK(args.flags["top-k"] ?? args.flags.topK);
+    const result = await searchKnowledgeFromCwd(process.cwd(), query, { topK });
+
+    console.log("Knowledge search");
+    console.log(`Database: ${result.databasePath}`);
+    console.log(`Query:    ${query}`);
+
+    if (result.results.length === 0) {
+      console.log("No matching knowledge chunks found.");
+      return;
+    }
+
+    console.log("");
+
+    for (const [index, item] of result.results.entries()) {
+      const source = [
+        item.source.path,
+        item.source.section ? `section: ${item.source.section}` : null,
+        item.source.locator,
+      ].filter(Boolean).join(" | ");
+
+      console.log(`${index + 1}. ${source}`);
+      console.log(`   score: ${item.score}`);
+      console.log(`   ${oneLine(item.content)}`);
+    }
+
+    return;
+  }
+
+  throw new Error(
+    "Usage: agentkit knowledge add <path-or-url> | sync | inspect | search <query> [--top-k <number>]",
+  );
+}
+
+function printIngestSummary(label: string, summary: Awaited<ReturnType<typeof addKnowledgeSourceFromCwd>>): void {
+  console.log(label);
+  console.log(`Database: ${summary.databasePath}`);
+  console.log(`${summary.indexed} indexed, ${summary.skipped} skipped, ${summary.failed} failed, ${summary.chunksCreated} chunks`);
+
+  if (summary.results.length > 0) {
+    console.log("");
+    console.log("source\tstatus\tchunks\tmessage");
+
+    for (const result of summary.results) {
+      console.log([result.source, result.status, String(result.chunksCreated), result.message].join("\t"));
+    }
+  }
+
+  if (summary.failed > 0) {
+    process.exitCode = 1;
+  }
+}
+
+function parseTopK(value: unknown): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const topK = Number(value);
+
+  if (!Number.isInteger(topK) || topK <= 0 || topK > 50) {
+    throw new Error("knowledge search --top-k must be a positive integer no larger than 50.");
+  }
+
+  return topK;
+}
+
+function oneLine(value: string): string {
+  const compact = value.replace(/\s+/g, " ").trim();
+  return compact.length <= 220 ? compact : `${compact.slice(0, 217)}...`;
+}

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/deploy-readiness.ts

@@ -179,6 +179,25 @@ export async function checkDeployReadiness(options: {
     });
   }
 
+  if (context.knowledge.enabled) {
+    if (context.knowledge.databaseDriver !== "turso") {
+      checks.push({
+        status: "fail",
+        title: "Knowledge storage",
+        message: "Hosted Knowledge requires a Turso database so indexed chunks are available to the Cloudflare runtime.",
+        action: 'set storage.database.driver: "turso" in agentkit.config.ts before deploying Knowledge',
+      });
+    } else {
+      checks.push({
+        status: "pass",
+        title: "Knowledge storage",
+        message: `Knowledge is configured with ${context.knowledge.sourceCount} source${
+          context.knowledge.sourceCount === 1 ? "" : "s"
+        } and Turso storage.`,
+      });
+    }
+  }
+
   if (context.userManagedSecrets.length === 0) {
     checks.push({
       status: "pass",