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

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,7 @@ 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.
 
 Optional shortcut when copying a prompt into another coding agent:
 

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.4",
+  "version": "0.1.0-alpha.6",
   "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/args.ts

@@ -0,0 +1,36 @@
+export type ParsedArgs = {
+  command?: string;
+  positional: string[];
+  flags: Record<string, string | boolean>;
+};
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const [command, ...rest] = argv;
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const value = rest[index];
+
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+
+    const name = value.slice(2);
+    const next = rest[index + 1];
+
+    if (next && !next.startsWith("--")) {
+      flags[name] = next;
+      index += 1;
+    } else {
+      flags[name] = true;
+    }
+  }
+
+  return { command, positional, flags };
+}
+
+export function isHelpRequested(args: ParsedArgs): boolean {
+  return args.flags.help === true || args.flags.h === true || args.positional.includes("--help") || args.positional.includes("-h");
+}

package/src/cli/cloud-client.ts

@@ -0,0 +1,257 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { AgentKitError } from "../runtime/errors";
+import { defaultAgentKitCloudApiUrl } from "./constants";
+import { parseCloudApiUrl } from "./flags";
+
+export type CloudAuthConfig = {
+  apiUrl: string;
+  token: string;
+  source?: "environment" | "file";
+};
+
+export type CloudMeResponse = {
+  account?: {
+    email?: string;
+    status?: string;
+  };
+};
+
+export type CloudCapabilitiesResponse = {
+  capabilities?: Array<{
+    name?: string;
+    status?: string;
+  }>;
+};
+
+export type CloudLimitsResponse = {
+  online_agents?: {
+    account?: {
+      used?: number | null;
+      limit?: number | null;
+    };
+    global?: {
+      used?: number | null;
+      limit?: number | null;
+    };
+  };
+};
+
+export type DeployAccessTokenCreateResponse = {
+  access_token?: {
+    id?: string;
+    deploy_id?: string;
+    name?: string;
+    token?: string;
+  };
+};
+
+export type DeployAccessTokenListResponse = {
+  access_tokens?: Array<{
+    id?: string;
+    deploy_id?: string;
+    name?: string;
+  }>;
+};
+
+export type CloudSecretsResponse = {
+  secrets?: Array<{
+    name?: string;
+    status?: string;
+    updated_at?: string;
+  }>;
+};
+
+export function cloudAuthPath(): string {
+  return join(homedir(), ".agentkit", "cloud.json");
+}
+
+export async function readCloudAuth(): Promise<CloudAuthConfig | null> {
+  if (process.env.AGENTKIT_CLOUD_API_TOKEN) {
+    return {
+      apiUrl: process.env.AGENTKIT_CLOUD_API_URL ?? defaultAgentKitCloudApiUrl,
+      token: process.env.AGENTKIT_CLOUD_API_TOKEN,
+      source: "environment",
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(await readFile(cloudAuthPath(), "utf8"));
+
+    if (parsed && typeof parsed === "object" && typeof parsed.token === "string") {
+      return {
+        apiUrl: typeof parsed.apiUrl === "string" ? parsed.apiUrl : defaultAgentKitCloudApiUrl,
+        token: parsed.token,
+        source: "file",
+      };
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+export async function writeCloudAuth(config: CloudAuthConfig): Promise<void> {
+  await mkdir(join(homedir(), ".agentkit"), { recursive: true });
+  await writeFile(cloudAuthPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function clearCloudAuth(): Promise<void> {
+  await rm(cloudAuthPath(), { force: true });
+}
+
+export async function resolveCloudApiUrl(flag: string | boolean | undefined): Promise<string> {
+  if (flag !== undefined) {
+    return parseCloudApiUrl(flag);
+  }
+
+  const auth = await readCloudAuth();
+  return auth?.apiUrl ?? parseCloudApiUrl(undefined);
+}
+
+export async function verifyCloudLogin(
+  apiUrl: string,
+  token: string,
+): Promise<{ me: CloudMeResponse; capabilities: CloudCapabilitiesResponse }> {
+  const me = await cloudApiRequestWithToken<CloudMeResponse>(apiUrl, "/v1/me", token, { method: "GET" });
+  const capabilities = await cloudApiRequestWithToken<CloudCapabilitiesResponse>(
+    apiUrl,
+    "/v1/me/capabilities",
+    token,
+    { method: "GET" },
+  );
+
+  return { me, capabilities };
+}
+
+export async function cloudGet<T>(apiUrl: string, path: string): Promise<T> {
+  const response = await cloudFetch(apiUrl, path);
+  const payload = await response.json();
+
+  if (!response.ok) {
+    throw new Error(readCloudError(payload, response.status));
+  }
+
+  return payload as T;
+}
+
+export async function cloudPost<T>(apiUrl: string, path: string, body: unknown): Promise<T> {
+  const response = await cloudFetch(apiUrl, path, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const payload = await response.json();
+
+  if (!response.ok) {
+    throw new Error(readCloudError(payload, response.status));
+  }
+
+  return payload as T;
+}
+
+export function cloudFetch(apiUrl: string, path: string, init: RequestInit = {}): Promise<Response> {
+  const headers = new Headers(init.headers);
+  const apiToken = process.env.AGENTKIT_CLOUD_API_TOKEN;
+
+  if (apiToken && !headers.has("Authorization")) {
+    headers.set("Authorization", `Bearer ${apiToken}`);
+  }
+
+  return fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {
+    ...init,
+    headers,
+  });
+}
+
+export async function cloudApiRequest(apiUrl: string, path: string, init: RequestInit): Promise<unknown> {
+  const auth = await readCloudAuth();
+  const headers = new Headers(init.headers);
+
+  if (!headers.has("Content-Type") && init.body !== undefined) {
+    headers.set("Content-Type", "application/json");
+  }
+
+  if (auth?.token && !headers.has("Authorization")) {
+    headers.set("Authorization", `Bearer ${auth.token}`);
+  }
+
+  const response = await fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {
+    ...init,
+    headers,
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    const code =
+      payload && typeof payload === "object" && "error" in payload
+        ? String((payload as { error?: { code?: unknown } }).error?.code ?? "cloud_request_failed")
+        : "cloud_request_failed";
+    let message = readCloudError(payload, response.status);
+
+    if (code === "auth_token_invalid") {
+      message = `${message} Token source: ${auth ? formatCloudAuthSource(auth) : "none"}. Run: agentkit login --token <token>`;
+    }
+
+    throw new AgentKitError(code, message);
+  }
+
+  return payload;
+}
+
+export async function cloudApiRequestWithToken<T>(
+  apiUrl: string,
+  path: string,
+  token: string,
+  init: RequestInit,
+): Promise<T> {
+  const headers = new Headers(init.headers);
+
+  if (!headers.has("Content-Type") && init.body !== undefined) {
+    headers.set("Content-Type", "application/json");
+  }
+
+  headers.set("Authorization", `Bearer ${token}`);
+
+  const response = await fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {
+    ...init,
+    headers,
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    const code =
+      payload && typeof payload === "object" && "error" in payload
+        ? String((payload as { error?: { code?: unknown } }).error?.code ?? "cloud_request_failed")
+        : "cloud_request_failed";
+    throw new AgentKitError(code, readCloudError(payload, response.status));
+  }
+
+  return payload as T;
+}
+
+export function readCloudError(payload: unknown, status: number): string {
+  if (payload && typeof payload === "object" && "error" in payload) {
+    const error = (payload as { error?: { message?: unknown } }).error;
+    if (typeof error?.message === "string") {
+      return error.message;
+    }
+  }
+
+  return `AgentKit Cloud request failed with HTTP ${status}.`;
+}
+
+export function formatCloudAuthSource(auth: CloudAuthConfig): string {
+  if (auth.source === "environment") {
+    return "AGENTKIT_CLOUD_API_TOKEN";
+  }
+
+  if (auth.source === "file") {
+    return cloudAuthPath();
+  }
+
+  return "AgentKit Cloud auth";
+}