@andreprado/agentkit 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,69 @@
+# AgentKit
+
+AgentKit is a CLI-first toolkit for creating, running, inspecting, and deploying Agent Capsules.
+
+## Quick Start
+
+```sh
+npx @andreprado/agentkit@alpha new support-agent --template support
+cd support-agent
+npm run dev
+npm run chat -- --message "hello"
+```
+
+For a Portuguese dental-office starter, use:
+
+```sh
+npx @andreprado/agentkit@alpha new clara-dentista --template dentista
+```
+
+`agentkit new` installs the generated capsule dependencies by default so `agentkit.config.ts` resolves `@andreprado/agentkit` immediately in editors. Use `--no-install` only for offline or scripted scaffolds where you want to run `npm install` later.
+
+Generated capsules use the built-in `test/fake` provider by default, so the first local run works without provider keys.
+
+## What To Know First
+
+```sh
+agentkit new <name> [--template blank|support|dentista] [--no-install]
+agentkit dev
+agentkit chat --message <text> [--conversation-id <id>]
+agentkit inspect
+```
+
+Once the capsule is running:
+
+```sh
+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.
+
+## Deploy Later
+
+```sh
+agentkit login --token <token>
+agentkit deploy doctor
+agentkit secret set OPENAI_API_KEY --from-local-env
+agentkit deploy
+agentkit deploy status
+agentkit chat-ui --deploy
+```
+
+Production secrets are managed secrets, not committed `.env` values.
+Private hosted deploys automatically store a local chat/UI deploy access token at `.agentkit/chat-access-token.json`. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy without exposing that token to browser code.
+
+The npm package contains the public CLI/runtime/client surface only. AgentKit Cloud's control-plane server, operator commands, Postgres store, and Cloudflare/Turso/R2 publisher live in the private repo workspace and are not part of the published package.
+
+## Full Reference
+
+`agentkit --help` keeps the first surface focused. Run `agentkit help commands` for the full CLI reference and `agentkit docs full` to print the path to the full agent-facing operating contract.

package/bin/agentkit.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const tsxCli = require.resolve("tsx/cli");
+const entry = join(packageRoot, "src/cli/index.ts");
+
+const result = spawnSync(process.execPath, [tsxCli, entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? (result.signal ? 1 : 0));

package/docs/guides/add-channel.md

@@ -0,0 +1,114 @@
+# Add A Channel
+
+## Goal
+
+Add a hosted messaging channel to an Agent Capsule, create the hosted channel resource, and verify that inbound messages become AgentKit channel deliveries without exposing secrets.
+
+## When To Use It
+
+Use this when the agent should receive messages from website chat, Telegram, or WhatsApp through AgentKit-owned webhook infrastructure.
+
+## Commands
+
+```sh
+agentkit inspect
+agentkit deploy
+agentkit channels list
+agentkit channels add website website-chat
+agentkit channels add telegram support-telegram
+agentkit channels add whatsapp support-whatsapp --provider zapster
+agentkit channels setup support-telegram
+agentkit channels status support-telegram
+agentkit channels test support-telegram --message "hello"
+agentkit channels deliveries list support-telegram
+```
+
+Use `--api <url>` with hosted commands when testing against a non-default AgentKit Cloud API.
+
+## Files Created Or Edited
+
+- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, or `whatsappChannel`.
+- `.agentkit/deploy.json`: written by `agentkit deploy`; used by `agentkit channels ...`.
+- No user Turso tables: AgentKit channel resources, dedupe, identities, queue state, and delivery logs are control-plane owned.
+- Website channel clients must send `AGENTKIT_WEBSITE_CHANNEL_TOKEN` as `Authorization: Bearer <token>` or `X-AgentKit-Channel-Token`.
+
+## Minimal Working Example
+
+```ts
+import { defineAgent, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [
+    websiteChannel({ name: "website-chat" }),
+    telegramChannel({ name: "support-telegram" }),
+    whatsappChannel({ name: "support-whatsapp", provider: "zapster" }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+## Buffer Bursty Messages
+
+Use `buffer` when clients send several short messages in a row and the agent should answer once.
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Buffering is scoped to one channel conversation. AgentKit still validates and dedupes each provider webhook, then stores the messages in a short-lived channel buffer. When the quiet window expires, AgentKit creates one agent run with the buffered messages and sends one outbound reply.
+
+Use `buffer: { mode: "off" }` or omit `buffer` to process each inbound message as its own agent run.
+
+## Safety Rules
+
+- Never put provider token values in `agentkit.config.ts`.
+- Keep local values in ignored `.env`; hosted production uses managed secrets with no readback.
+- Treat channel webhook URLs as public transport endpoints. Provider validation or the AgentKit website channel token controls authenticity.
+- Keep channels separate from tools. Channels deliver user messages; tools let the agent call external systems.
+- Keep `maxMessages` and `maxChars` bounded so one burst cannot create an oversized prompt or unexpected model spend.
+
+## Verification
+
+```sh
+npm run typecheck
+bun test
+agentkit inspect
+agentkit channels list
+agentkit channels test support-telegram --message "hello"
+agentkit channels deliveries list support-telegram
+```
+
+Expected hosted status includes `NAME`, `TYPE`, `PROVIDER`, `STATUS`, and `LAST_EVENT`. Secret output is name plus `set` or `missing`, never the value.
+
+## Troubleshooting
+
+`No .agentkit/deploy.json found`:
+Run `agentkit deploy` before creating hosted channel resources.
+
+`channel_secret_missing`:
+Set the named hosted secret. Do not add production values to `.env`.
+
+`channel_signature_invalid`:
+The provider webhook secret, token, or origin header does not match the managed secret.
+
+`channel_limit_exceeded`:
+The channel daily message limit was reached. Website requests return `429`; Telegram and WhatsApp are acknowledged and skipped to avoid provider retry storms.
+
+Buffered messages stay in `buffered` delivery state until the quiet window or max wait flushes them into one queued run.

package/docs/guides/add-knowledge.md

@@ -0,0 +1,134 @@
+# Add Knowledge
+
+Knowledge is AgentKit's native retrieval layer for facts the agent should not invent: policies, prices, service details, FAQs, CSV tables, procedures, and internal reference docs.
+
+Use Knowledge when the answer should come from source files instead of the base prompt. Do not use Knowledge for secrets, credentials, or data that should only be fetched live through a tool.
+
+## Configure
+
+Create a `knowledge/` directory in the Agent Capsule and list the sources in `agentkit.config.ts`:
+
+```ts
+export default defineAgent({
+  // ...
+  knowledge: {
+    sources: [
+      "knowledge/faq.md",
+      { path: "knowledge/prices.csv", title: "Prices" },
+    ],
+    retrieval: {
+      topK: 8,
+      hybrid: false,
+    },
+  },
+});
+```
+
+Local Knowledge supports `.md`, `.markdown`, `.txt`, and `.csv` files. Markdown is chunked by headings, text is chunked by paragraphs, and CSV rows preserve column headers.
+
+The default embedding provider is `none`, which gives local lexical search without an API key. To add embeddings, configure them separately from the chat provider:
+
+```ts
+knowledge: {
+  sources: ["knowledge/faq.md"],
+  embedding: {
+    provider: "openai",
+    model: "text-embedding-3-small",
+    secret: "KNOWLEDGE_OPENAI_API_KEY",
+  },
+  retrieval: {
+    topK: 8,
+    hybrid: true,
+  },
+},
+```
+
+Then set the local secret without committing it:
+
+```sh
+printf %s "$KNOWLEDGE_OPENAI_API_KEY" | agentkit env set KNOWLEDGE_OPENAI_API_KEY --stdin
+```
+
+## Index Locally
+
+Index one source:
+
+```sh
+agentkit knowledge add knowledge/faq.md
+```
+
+Sync all configured sources:
+
+```sh
+agentkit knowledge sync
+```
+
+Inspect indexed sources:
+
+```sh
+agentkit knowledge inspect
+```
+
+Search locally:
+
+```sh
+agentkit knowledge search "refund policy" --top-k 3
+```
+
+`knowledge add` is useful for one-off local indexing. `knowledge sync` validates and indexes all configured `knowledge.sources` on demand. `agentkit dev` and `agentkit chat` also sync configured Knowledge automatically before local runs, and unchanged files are skipped by content hash.
+
+When embeddings are configured locally, AgentKit stores canonical Knowledge chunks in `.agentkit/agentkit.db` and rebuilds a local libSQL vector sidecar at `.agentkit/agentkit.vectors.db`. Local semantic search uses the sidecar's native `libsql_vector_idx` path and falls back to stored JSON embeddings if the native vector path is unavailable.
+
+## Agent Behavior
+
+When `knowledge` is configured, AgentKit automatically registers the internal tool `agentkit_search_knowledge` during chat runs 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, or chunk IDs.
+
+With the deterministic `test/fake` provider, 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
+```
+
+The retrieved chunks are persisted as internal tool output in local SQLite for evals and inspection, but they are not shown directly to the user.
+
+## Hosted Deploy
+
+Cloudflare Knowledge deploys require AgentKit-managed Turso storage:
+
+```ts
+storage: {
+  driver: "agentkit",
+  database: {
+    driver: "turso",
+    schema: "./schema.sql",
+  },
+},
+```
+
+`agentkit deploy doctor` and `agentkit build --target cloudflare` fail with an actionable error when Knowledge is configured without Turso. The Cloudflare artifact includes the Knowledge manifest, required embedding secret names, internal Knowledge schema, local source file contents, prompt policy, and hosted `agentkit_search_knowledge` runtime.
+
+During `agentkit deploy`, AgentKit Cloud provisions or resolves the project Turso database, applies the Knowledge schema, chunks every packaged local source, creates embeddings when an embedding provider is configured, and writes sources, chunks, embedding metadata, FTS rows, and a native Turso `libsql_vector_idx` index into Turso before publishing the Worker. Removed configured sources are deleted from the hosted Knowledge tables during sync.
+
+Local `agentkit knowledge add`, `agentkit knowledge sync`, `agentkit dev`, and `agentkit chat` index configured Knowledge into the local SQLite database and local libSQL vector sidecar. Hosted deploy syncs configured local Knowledge sources automatically from the deploy artifact so embedding secrets stay server-side and private source material does 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.
+
+## Safety Rules
+
+- Do not put API keys, passwords, private tokens, `.env` contents, or credential exports in Knowledge files.
+- Treat committed Knowledge files as repository content. Use a private repo for private business docs.
+- Use tools for live customer records, payments, orders, or anything requiring authorization checks.
+- Use explicit `title` fields for CSVs or ambiguous files so search results have useful citations.
+- Use `agentkit knowledge sync` to validate source changes explicitly; local `agentkit dev` and `agentkit chat` also sync configured sources automatically.
+
+## Troubleshooting
+
+- `No knowledge.sources are configured`: add `knowledge.sources` to `agentkit.config.ts` or use `agentkit knowledge add <path>`.
+- `Knowledge source paths must stay inside the Agent Capsule`: move the source under the capsule root, usually `knowledge/`.
+- `Local Knowledge currently supports .md, .txt, and .csv files`: convert the source or add a tool for unsupported formats.
+- `Knowledge embeddings require missing secret`: set the env var named by `knowledge.embedding.secret`.
+- Hosted build says Turso is required: add `storage.database.driver: "turso"` before deploying Knowledge.

package/docs/guides/add-tool.md

@@ -0,0 +1,342 @@
+# Add A Tool
+
+## Goal
+
+Add a TypeScript tool to an Agent Capsule, register it in `agentkit.config.ts`, validate its input and output, and verify that calls are stored without leaking secrets.
+
+## When To Use This
+
+Use this when the agent needs to call code, read an API, query a database, or perform a small action behind a typed contract.
+
+## Commands
+
+From a capsule root:
+
+```sh
+mkdir -p tools
+$EDITOR tools/lookup-order.ts
+$EDITOR agentkit.config.ts
+npm run typecheck
+npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
+npm run agentkit -- conversations list
+```
+
+## Files Created Or Edited
+
+Create:
+
+```txt
+tools/lookup-order.ts
+```
+
+Edit:
+
+```txt
+agentkit.config.ts
+.env.schema
+.env
+```
+
+Edit `.env.schema` only for secret names. Put secret values in ignored `.env`.
+Run local AgentKit commands normally; tools, evals, chat, and inspect load `.env` through the same AgentKit loader.
+
+## Minimal Working Example
+
+`tools/lookup-order.ts`:
+
+```ts
+import { defineTool } from "@andreprado/agentkit";
+
+const orders: Record<string, { status: string; eta: string }> = {
+  A100: { status: "preparing", eta: "today" },
+  B200: { status: "shipped", eta: "tomorrow" },
+};
+
+export const lookupOrder = defineTool({
+  name: "lookup_order",
+  description: "Looks up a demo support order by order id.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      orderId: { type: "string" },
+    },
+    required: ["orderId"],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      orderId: { type: "string" },
+      found: { type: "boolean" },
+      status: { type: "string" },
+      eta: { type: "string" },
+    },
+    required: ["orderId", "found", "status", "eta"],
+  },
+  execute(input: { orderId: string }) {
+    const order = orders[input.orderId];
+
+    if (!order) {
+      return {
+        orderId: input.orderId,
+        found: false,
+        status: "unknown",
+        eta: "unknown",
+      };
+    }
+
+    return {
+      orderId: input.orderId,
+      found: true,
+      status: order.status,
+      eta: order.eta,
+    };
+  },
+});
+```
+
+Register it:
+
+```ts
+import { defineAgent } from "@andreprado/agentkit";
+import { lookupOrder } from "./tools/lookup-order";
+
+export default defineAgent({
+  tools: [lookupOrder],
+});
+```
+
+Direct tool test:
+
+```sh
+npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
+```
+
+Expected output:
+
+```json
+{
+  "orderId": "A100",
+  "found": true,
+  "status": "preparing",
+  "eta": "today"
+}
+```
+
+## Database Tool Pattern
+
+Use this when a tool needs agent-owned tables and must work locally and after deploy through the same AgentKit database helper.
+
+Recommended contract:
+
+- Put all agent-owned tables in `schema.sql`.
+- Keep deploy-ready capsules on `storage.driver: "agentkit"`.
+- Local `agentkit chat`, `agentkit tool`, `agentkit dev`, and eval runs apply `schema.sql` to local development storage.
+- Use `agentkit db migrate`, `agentkit db reset --yes`, `agentkit db seed [--file seed.sql]`, and `agentkit db shell` for local database setup and inspection.
+- Hosted deploy migrates/provisions the managed database internally and applies the same `schema.sql`.
+- Tools use `ctx.db` as the canonical helper. `ctx.database` and `ctx.storage.sql` are supported aliases.
+- Use `ctx.db.batch([...])` for atomic writes. Local tools can also use `ctx.db.transaction(async (tx) => ...)`.
+- Do not import local database drivers or Node-only APIs from a tool. Use runtime services such as `ctx.db`.
+
+`agentkit.config.ts`:
+
+```ts
+import { defineAgent } from "@andreprado/agentkit";
+import { scheduleAppointment } from "./tools/schedule-appointment";
+
+export default defineAgent({
+  name: "appointments",
+  runtime: "edge",
+  provider: {
+    name: "test",
+    model: "fake",
+  },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [scheduleAppointment],
+  access: {
+    mode: "private",
+  },
+  storage: {
+    driver: "agentkit",
+  },
+});
+```
+
+`schema.sql`:
+
+```sql
+CREATE TABLE IF NOT EXISTS appointments (
+  id TEXT PRIMARY KEY,
+  client_name TEXT NOT NULL,
+  starts_at TEXT NOT NULL,
+  notes TEXT,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (starts_at)
+);
+```
+
+`schema.sql` is an idempotent bootstrap file in v1. Prefer `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive `ALTER TABLE` statements. AgentKit does not run destructive schema changes or ordered `migrations/*.sql` automatically yet.
+
+`tools/schedule-appointment.ts`:
+
+```ts
+import { defineTool } from "@andreprado/agentkit";
+
+export const scheduleAppointment = defineTool({
+  name: "schedule_appointment",
+  description: "Schedules an appointment in the agent database.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      clientName: { type: "string" },
+      startsAt: { type: "string" },
+      notes: { type: "string" },
+    },
+    required: ["clientName", "startsAt"],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      id: { type: "string" },
+      clientName: { type: "string" },
+      startsAt: { type: "string" },
+    },
+    required: ["id", "clientName", "startsAt"],
+    additionalProperties: false,
+  },
+  async execute(input: { clientName: string; startsAt: string; notes?: string }, ctx) {
+    const id = crypto.randomUUID();
+
+    await ctx.db.execute(
+      "INSERT INTO appointments (id, client_name, starts_at, notes) VALUES (?, ?, ?, ?)",
+      [id, input.clientName, input.startsAt, input.notes ?? null],
+    );
+
+    const result = await ctx.db.query("SELECT id, client_name, starts_at FROM appointments WHERE id = ?", [id]);
+    const appointment = result.rows[0];
+
+    return {
+      id: String(appointment.id),
+      clientName: String(appointment.client_name),
+      startsAt: String(appointment.starts_at),
+    };
+  },
+});
+```
+
+Local test:
+
+```sh
+npm run agentkit -- tool schedule_appointment --input '{"clientName":"Ada Lovelace","startsAt":"2026-06-01T10:00:00Z"}'
+npm run agentkit -- db shell
+```
+
+Build/deploy:
+
+```sh
+npm run agentkit -- inspect
+npm run agentkit -- build
+npm run agentkit -- deploy
+```
+
+`inspect` shows the local runtime state and declared secret names. The user does not create hosted databases or buckets manually; AgentKit handles deploy infrastructure internally.
+
+`ctx.runtime` tells a tool where it is running:
+
+```ts
+ctx.runtime // { environment, invocation, target, database }
+```
+
+Use it for diagnostics only, not for bypassing AgentKit runtime services or choosing deploy infrastructure.
+
+## Safety Rules
+
+- Use `inputSchema` for every tool.
+- Use `outputSchema` when downstream behavior depends on shape.
+- Set `additionalProperties: false` for strict object inputs.
+- Use JSON Schema unions such as `type: ["string", "null"]` when `null` is meaningful.
+- Optional object properties sent as `null` are treated as omitted unless the property schema allows `null`.
+- List tool secrets in the tool `secrets` field.
+- Do not read arbitrary `process.env` inside tools.
+- Use `ctx.secrets.SECRET_NAME`.
+- Set `timeoutMs` for slow external calls.
+- Set `visibility: "internal"` for operational outputs such as classifications, scores, routing labels, fraud decisions, or other fields the agent should persist but not reveal literally to the user.
+- Do not log secret values.
+
+Internal output example:
+
+```ts
+export const triageLead = defineTool({
+  name: "triage_real_estate_lead",
+  description: "Classifies an incoming lead for routing.",
+  visibility: "internal",
+  inputSchema: {
+    type: "object",
+    properties: {
+      email: { type: "string" },
+    },
+    required: ["email"],
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      status: { type: "string" },
+      score: { type: "integer" },
+    },
+    required: ["status", "score"],
+  },
+  execute() {
+    return { status: "hot", score: 92 };
+  },
+});
+```
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
+npm run agentkit -- conversations list
+```
+
+Optional SQLite check:
+
+```sh
+sqlite3 .agentkit/agentkit.db 'select tool_name,visibility,status,input_json,output_json from tool_calls;'
+```
+
+Expected:
+
+- TypeScript passes.
+- The tool command prints the JSON output.
+- `tool_calls` has one completed row.
+- Secret values do not appear in `.agentkit/agentkit.db`.
+
+## Troubleshooting
+
+`tool_not_found`:
+
+Import the tool and add it to `tools: [...]` in `agentkit.config.ts`.
+
+`tool_validation_error`:
+
+Compare the JSON message input to `inputSchema`.
+
+`tool_secret_missing`:
+
+Add the secret name to `.env.schema`, write the local value to ignored `.env`, and inspect again:
+
+```sh
+printf %s "$CRM_API_KEY" | npm run agentkit -- env set CRM_API_KEY --stdin
+npm run agentkit -- inspect
+```
+
+Tool hangs:
+
+Set `timeoutMs`, pass `ctx.signal` to external fetch calls, and retry.
+
+## Backend Contracts Used
+
+Local tool calls are stored in SQLite `tool_calls`. Hosted tools later run under the managed Tool Gateway contract with scoped secrets, permission checks, timeouts, and redacted logs.