@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/templates/support.ts

@@ -63,6 +63,7 @@ node_modules/
         contents: `# Optional: add real provider keys after switching away from test/fake.
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
+OPENROUTER_API_KEY=
 `,
       },
       {
@@ -110,7 +111,9 @@ export default defineAgent({
       },
       {
         path: "tools/lookup-order.ts",
-        contents: `const orders: Record<string, { status: string; eta: string }> = {
+        contents: `import type { AgentTool } from "@andreprado/agentkit";
+
+const orders: Record<string, { status: string; eta: string }> = {
   A100: { status: "preparing", eta: "today" },
   B200: { status: "shipped", eta: "tomorrow" },
 };
@@ -156,7 +159,7 @@ export const lookupOrder = {
       eta: order.eta,
     };
   },
-};
+} satisfies AgentTool;
 `,
       },
       {
@@ -168,13 +171,18 @@ Help users with clear answers. When order status is needed, use the lookup_order
       },
       {
         path: "evals/smoke.eval.ts",
-        contents: `export default {
+        contents: `import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
   name: "smoke",
   input: "Say hello as a support agent.",
   expect: {
-    contains: "hello",
+    response: {
+      caseInsensitiveContains: "hello",
+      maxLength: 200,
+    },
   },
-};
+});
 `,
       },
       {
@@ -189,33 +197,48 @@ When the owner opens this folder in Codex, Claude Code, or another coding agent
 
 Start building immediately:
 
-- Read \`AGENTKIT.md\` and the full docs path from \`npm run agentkit -- docs full\`.
+- Start with \`skills/agentkit-capsule/SKILL.md\`, then use \`npm run agentkit -- docs llms\` as the docs router.
+- Create or update \`AGENT_SPEC.md\` from the owner's request with \`npm run agentkit -- spec init --brief "<owner request>"\`; the owner should not fill this file by hand before work starts.
 - Infer the first useful version from the owner's request.
 - Edit \`prompts/instructions.md\` for support behavior.
 - Edit \`agentkit.config.ts\` for provider, tools, secrets, access, and storage.
 - Add or replace TypeScript tools under \`tools/\` when the requested support agent needs actions or external data.
+- Add \`sync.ts\`, \`seed.sql\`, and ordered \`migrations/*.sql\` when the support agent depends on external catalogs or production-shaped data changes.
+- Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; you decide the implementation from the owner's brief.
 - Ask follow-up questions only when missing information blocks a safe local implementation.
 - State assumptions in the final response.
 
 ## Local Commands
 
-- \`npm install\`: install capsule dependencies.
+- \`npm install\`: restore capsule dependencies if this capsule used \`--no-install\`, install failed, or \`node_modules\` was deleted.
 - \`npm run chat -- --message "hello"\`: send one local chat message.
 - \`npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'\`: test the example tool directly.
 - \`npm run eval\`: run agent evals.
+- \`npm run agentkit -- spec check\`: verify the local agent implementation contract exists.
+- \`npm run agentkit -- eval from-conversation <conversation-id>\`: turn a real conversation into a regression eval.
+- \`npm run agentkit -- conversations trace <conversation-id>\`: inspect messages, runs, tool calls, inputs, outputs, rendered output, and final responses.
 - \`npm run dev\`: run the local Agent Capsule runtime.
 - \`npm run agentkit -- inspect\`: print machine-readable capsule state.
-- \`npm run agentkit -- env set <NAME> <VALUE>\`: write a local secret value to ignored \`.env\`.
+- \`printf %s "$VALUE" | npm run agentkit -- env set <NAME> --stdin\`: write a local secret value to ignored \`.env\` without putting it in shell history.
 - \`npm run agentkit -- env list\`: list local secret names without printing values.
-- \`npm run agentkit -- docs full\`: print the full AgentKit contract path.
+- \`npm run agentkit -- docs llms\`: print the lightweight AgentKit docs router.
+- \`npm run agentkit -- docs full\`: print the full AgentKit contract path only when a skill asks for it.
+
+## Testing With A UI
+
+- Local UI: run \`npm run dev\`, open the printed \`Chat:\` URL, and tell the owner the exact URL.
+- Hosted UI: after \`npm run agentkit -- deploy\`, run \`npm run agentkit -- chat-ui --deploy\`, open the printed \`Chat:\` URL, and tell the owner it is connected to the hosted deploy.
+- \`test/fake\` is deterministic. It is useful for scaffold checks, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality.
+- Before claiming real conversation behavior is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
 
 ## Hosted Deploy
 
 - Local scaffold, chat, eval, dev, inspect, tool, and build commands are token-free.
 - Hosted deploy requires an invited AgentKit Cloud alpha token. If no token is stored yet, ask the owner for one and run \`npm run agentkit -- login --token <token>\`.
-- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> <VALUE>\`, not into committed files.
+- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`, not into committed files or shell history.
 - Deploy with \`npm run agentkit -- deploy\`, then check \`npm run agentkit -- deploy status\`.
-- Create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\` when a website or app needs to call the hosted agent.
+- Hosted deploy writes the local chat/UI deploy access token to \`.agentkit/chat-access-token.json\`. Create extra client-facing tokens with \`npm run agentkit -- access token create <name> --out <path>\` when a separate website or app needs its own credential.
+- Use \`npm run agentkit -- deploy --smoke "hello"\` or \`npm run agentkit -- deploy smoke --message "hello"\` for an official hosted chat smoke check.
 - Do not run operator/admin commands from a user capsule.
 
 ## Files
@@ -248,42 +271,71 @@ Example owner request:
 Turn the request into a working local capsule:
 
 - Update \`prompts/instructions.md\` with domain-specific behavior, boundaries, intake questions, and escalation rules.
+- Create or update \`AGENT_SPEC.md\` with \`npm run agentkit -- spec init --brief "<owner request>"\`. The owner gives the general idea; the coding agent turns it into the structured contract.
 - Update \`agentkit.config.ts\` when tools, secrets, provider, or access rules change.
 - Add, replace, or remove TypeScript tools under \`tools/\` for real actions or external data.
+- Use \`npm run agentkit -- sync init\` when the agent needs catalog sync, fixture seed data, or ordered migrations.
 - Keep the first version runnable with \`test/fake\` unless the owner explicitly asks for a real provider.
+- Do not use a wizard or recipe. Build the capsule directly from the scaffold, the AgentKit contract, and the owner's brief.
 - Make practical assumptions and list them in your final response.
 - Ask follow-up questions only when missing information blocks a safe local implementation.
 
 ## Local Commands
 
 \`\`\`sh
-npm install
 npm run typecheck
 npm run agentkit -- inspect
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 npm run eval
 \`\`\`
 
+\`test/fake\` proves the scaffold and deterministic tool paths. It does not prove natural conversation quality.
+
+\`agentkit new\` installs dependencies by default. Run \`npm install\` only if the capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
+
 Set local development secrets without opening code:
 
 \`\`\`sh
-npm run agentkit -- env set OPENAI_API_KEY "<value>"
+printf %s "$OPENAI_API_KEY" | npm run agentkit -- env set OPENAI_API_KEY --stdin
 npm run agentkit -- inspect
 npm run chat -- --message "hello"
 \`\`\`
 
+## Testing With A UI
+
+Local UI:
+
+\`\`\`sh
+npm run dev
+\`\`\`
+
+Open the printed \`Chat:\` URL and tell the owner the exact URL.
+
+Hosted deploy UI:
+
+\`\`\`sh
+npm run agentkit -- deploy
+npm run agentkit -- chat-ui --deploy
+\`\`\`
+
+Open the printed \`Chat:\` URL and tell the owner this local UI is connected to the hosted deploy.
+
+Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them. After they choose, update \`agentkit.config.ts\`, \`.env.schema\`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
+
 If you add a tool, also run a fake-provider tool smoke test:
 
 \`\`\`sh
 npm run agentkit -- tool tool_name --input '{}'
 \`\`\`
 
-For the full framework contract, read the path printed by:
+For the lightweight docs router, read the path printed by:
 
 \`\`\`sh
-npm run agentkit -- docs full
+npm run agentkit -- docs llms
 \`\`\`
 
+Read the full framework contract with \`npm run agentkit -- docs full\` only when a skill asks for it.
+
 ## Database Tools
 
 Tools that need agent-owned tables should use canonical \`ctx.db\` from the tool context. \`ctx.database\` and \`ctx.storage.sql\` are aliases. Do not import local database drivers or Node-only APIs in a tool.
@@ -305,9 +357,10 @@ This capsule is deploy-ready by default.
 1. Keep tools edge-safe and use \`ctx.db\` instead of importing database drivers.
 2. Run \`npm run agentkit -- build\` only when you want to validate the artifact locally.
 3. If the owner has not logged in yet, ask for an invited AgentKit Cloud alpha token and run \`npm run agentkit -- login --token <token>\`.
-4. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> <VALUE>\`.
+4. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`.
 5. Run \`npm run agentkit -- deploy\`.
-6. Create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\` when a website or app needs to call the hosted agent.
+6. Run \`npm run agentkit -- chat-ui --deploy\` to test the hosted agent through a local UI using the auto-created \`.agentkit/chat-access-token.json\`. Create extra client-facing deploy access tokens with \`npm run agentkit -- access token create <name> --out <path>\` when a separate website or app needs its own credential.
+7. Use \`npm run agentkit -- deploy --smoke "hello"\` during deploy or \`npm run agentkit -- deploy smoke --message "hello"\` afterward for an official hosted smoke check.
 
 AgentKit owns hosted infrastructure and production secrets. Do not put production secret values in this capsule. Do not run operator/admin commands from a user capsule.
 `,
@@ -321,8 +374,10 @@ Use AgentKit conventions when editing this support capsule.
 - The agent contract lives in \`agentkit.config.ts\`.
 - The example tool lives in \`tools/lookup-order.ts\`.
 - The default provider is \`test/fake\`, which can call tools from JSON messages during local tests.
+- Ask the owner which real provider to use before switching from \`test/fake\`; do not choose OpenRouter, OpenAI, or Anthropic automatically.
 - Keep required local secret names in \`.env.schema\` and values in ignored \`.env\`. AgentKit local commands load \`.env\` directly.
 - Treat the owner's natural-language request as the brief and start implementing inside this capsule.
+- Start with \`skills/agentkit-capsule/SKILL.md\` when the task is not obvious.
 `,
       },
       {
@@ -334,14 +389,18 @@ Generated by AgentKit as a support Agent Capsule.
 ## Setup
 
 \`\`\`sh
-npm install
 npm run chat -- --message "hello"
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 npm run eval
 npm run dev
 \`\`\`
 
+\`agentkit new\` installs dependencies by default. Run \`npm install\` only if this capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
+
 The support template includes a local \`lookup_order\` TypeScript tool and uses \`test/fake\` by default.
+\`test/fake\` does not validate real conversation quality. The owner must choose OpenRouter, OpenAI, Anthropic, or another supported provider before real model behavior is tested.
+
+For UI testing, run \`npm run dev\` and open the printed \`Chat:\` URL. After hosted deploy, run \`npm run agentkit -- chat-ui --deploy\` and open its printed \`Chat:\` URL.
 `,
       },
     ];

package/docs/guides/channels-production-handoff.md

@@ -1,99 +0,0 @@
-# Channels Production Handoff
-
-## Goal
-
-Move Channels from local fake control-plane tests to production safely.
-
-## Deployment Order
-
-1. Build and typecheck:
-
-```sh
-npm run typecheck
-bun test
-agentkit build --target cloudflare
-```
-
-2. Deploy AgentKit Cloud/control plane with:
-
-```txt
-Cloudflare Worker
-Cloudflare Queue for channel jobs
-Durable Object namespace for channel coordination
-R2 bucket for large/raw payload handoff when enabled
-Turso/Postgres control-plane tables for deploys, channels, deliveries, events, and identities
-```
-
-3. Set managed secrets:
-
-```txt
-OPENAI_API_KEY or another model provider key
-TELEGRAM_BOT_TOKEN
-TELEGRAM_WEBHOOK_SECRET
-ZAPSTER_API_KEY
-ZAPSTER_WEBHOOK_SECRET
-META_WHATSAPP_ACCESS_TOKEN
-META_WHATSAPP_APP_SECRET
-META_WHATSAPP_VERIFY_TOKEN
-```
-
-4. Create channels:
-
-```sh
-agentkit channels add telegram support-telegram
-agentkit channels add whatsapp support-whatsapp --provider zapster
-agentkit channels setup support-telegram --apply
-agentkit channels setup support-whatsapp
-```
-
-5. Run smoke checks:
-
-```sh
-agentkit channels status support-telegram
-agentkit channels test support-telegram --message "hello"
-agentkit channels status support-whatsapp
-agentkit channels test support-whatsapp --message "hello"
-agentkit channels deliveries list support-telegram --since 1h
-```
-
-## Local Fake Versus Real Provider Gates
-
-Default tests are offline and must pass without provider credentials:
-
-```sh
-bun test
-```
-
-Real-provider smoke tests are opt-in:
-
-```sh
-AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
-AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
-```
-
-Telegram smoke requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
-
-Zapster smoke requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
-
-## Smoke Checks
-
-- Unknown channel ID returns `404` and creates no tenant record.
-- Invalid Telegram/Zapster signature returns `401` and creates a failed delivery.
-- Duplicate provider event returns `200` with `duplicate` and creates no second queue job.
-- Accepted inbound text creates one queue job and one outbound delivery.
-- Retryable failures dead-letter after the configured retry ceiling.
-- `channel_limit_exceeded` does not create queue backlog.
-
-## Rollback
-
-- Disable the channel resource first; do not delete delivery history.
-- Remove provider webhook registration if the provider keeps retrying.
-- Roll back the Worker only after queue drain or pause.
-- Keep managed secrets; rotate only if a secret may have leaked.
-
-## Production Defaults
-
-- Start with conservative per-channel daily message and cost limits.
-- Keep raw body storage disabled unless there is an explicit encrypted R2 retention policy.
-- Delivery APIs return hashes and redacted metadata, not payload bodies.
-- Turso remains reserved for the user's agent application data, not AgentKit channel plumbing.

package/docs/portable-deploy-release-checklist.md

@@ -1,41 +0,0 @@
-# Portable Deploy Release Checklist
-
-Run this before merging portable deploy target work.
-
-## Tests
-
-```sh
-bun test
-npm run typecheck
-npm run agentkit -- build --target cloudflare
-npm run agentkit -- build --target container
-npm run agentkit -- deploy --target vps --host agent.example.com --dry-run
-docker compose -f .agentkit/build/vps/compose.yaml config
-```
-
-## Smoke
-
-- Cloudflare build contains `worker.js`, `wrangler.jsonc`, `durable-object-schema.sql`, and `agent.manifest.json`.
-- Container build contains `server.js`, `Dockerfile`, `migrations/`, and `agent.manifest.json`.
-- VPS build contains `compose.yaml`, `.env.production.example`, `SECRETS.md`, and `PRODUCTION_HANDOFF.md`.
-- `/health`, `/_agentkit`, `/chat`, `/tools/:name`, `/files/:key`, and channel webhook fixtures pass on the local/container runtime.
-
-## Secrets
-
-```sh
-rg -n "sk-|OPENAI_API_KEY=.*[A-Za-z0-9]" .agentkit/build || true
-```
-
-Expected: no secret values. Generated files may contain secret names only.
-
-## Production Handoff
-
-- Cloudflare deploy has target-aware `.agentkit/deploy.json` with `target`, `runtime`, and `resources`.
-- VPS handoff documents `PORT`, `AGENTKIT_SQLITE_PATH`, reverse proxy expectations, smoke checks, SQLite backup, Postgres upgrade path, and rollback.
-- Rollback command is present in `.agentkit/build/vps/PRODUCTION_HANDOFF.md`.
-
-## External Smokes
-
-- Cloudflare deployed smoke requires Cloudflare credentials and a provider key.
-- Docker image smoke requires a running Docker daemon.
-- Telegram/Zapster real send smoke requires explicit provider credentials.