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

package/README.md

@@ -1,21 +1,60 @@
 # AgentKit
 
-AgentKit is a toolkit for creating, running, inspecting, and deploying Agent Capsules.
+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 install
 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
 ```
 
-Local scaffolding, development, inspection, evals, and builds do not require an AgentKit Cloud token. Hosted production deploys do:
+Once the capsule is running:
 
 ```sh
-agentkit login --token agk_user_...
+agentkit tool <name> [--input <path-or-json>]
+agentkit db migrate
+agentkit eval run
+agentkit conversations list
+```
+
+## Deploy Later
+
+```sh
+agentkit login --token <token>
 agentkit deploy doctor
-agentkit secret set OPENAI_API_KEY "$OPENAI_API_KEY"
+agentkit secret set OPENAI_API_KEY --from-local-env
 agentkit deploy
+agentkit deploy status
+agentkit chat-ui --deploy
 ```
 
-See `docs/guides/create-agent.md` and `docs/guides/prepare-deploy.md` for the user workflow.
+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/docs/guides/add-tool.md

@@ -329,7 +329,7 @@ Compare the JSON message input to `inputSchema`.
 Add the secret name to `.env.schema`, write the local value to ignored `.env`, and inspect again:
 
 ```sh
-npm run agentkit -- env set CRM_API_KEY "<value>"
+printf %s "$CRM_API_KEY" | npm run agentkit -- env set CRM_API_KEY --stdin
 npm run agentkit -- inspect
 ```
 

package/docs/guides/channels-implementation-map.md

@@ -0,0 +1,243 @@
+# Channels Implementation Map
+
+Source of truth: [`../../CHANNELS_PRD.md`](../../CHANNELS_PRD.md).
+
+Use this map before implementing Channels. It identifies the current AgentKit files that should absorb the Channels contract and the blocker order from `TASKS.md`.
+
+## Current State
+
+AgentKit already has the hosted deploy spine that Channels should extend:
+
+- Public config and exports live in `packages/agentkit/src/index.ts`.
+- Config loading and validation live in `packages/agentkit/src/runtime/config.ts`.
+- `agentkit inspect` state lives in `packages/agentkit/src/runtime/inspect.ts`.
+- Cloudflare artifact generation lives in `packages/agentkit/src/runtime/targets/cloudflare/build.ts`.
+- The CLI command switch lives in `packages/agentkit/src/cli/index.ts`.
+- Local AgentKit Cloud control-plane routes live in `packages/agentkit/src/runtime/deploy.ts`.
+- Local runtime conversation storage lives in `packages/agentkit/src/storage/sqlite.ts`.
+
+Channels should not start inside provider-specific code. The obvious implementation path is contract-first, fixture-first, then hosted ingress.
+
+## First Files To Edit
+
+### Config Contract
+
+Edit `packages/agentkit/src/index.ts` first.
+
+Add:
+
+- `AgentChannel`;
+- `WebsiteChannelConfig`;
+- `TelegramChannelConfig`;
+- `WhatsappChannelConfig`;
+- `ChannelType`;
+- `ChannelProvider`;
+- `websiteChannel(...)`;
+- `telegramChannel(...)`;
+- `whatsappChannel(...)`;
+- optional `channels?: AgentChannel[]` on `AgentConfig`.
+
+Reason: generated capsules import public helpers from `@andreprado/agentkit`, so the public contract must exist before config validation, templates, docs, or CLI commands can rely on it.
+
+### Config Validation
+
+Edit `packages/agentkit/src/runtime/config.ts` after the public types exist.
+
+Add validation for:
+
+- lowercase stable channel names;
+- unique names within a capsule;
+- supported type/provider combinations;
+- required channel secret name arrays;
+- `runtime: "edge"` when channels are configured for hosted use;
+- no secret values in channel config.
+
+Tests belong in `packages/agentkit/src/runtime/config.test.ts`.
+
+### Inspect State
+
+Edit `packages/agentkit/src/runtime/inspect.ts` after validation.
+
+Add:
+
+- channel summaries;
+- channel required secrets merged into the existing `secrets` status map;
+- no provider API values or webhook secret values.
+
+Tests belong in `packages/agentkit/src/runtime/config.test.ts` or a new focused inspect test if the file grows too large.
+
+### Build Manifest
+
+Edit `packages/agentkit/src/runtime/targets/cloudflare/build.ts` after inspect.
+
+Add channels to:
+
+- `AgentManifest`;
+- `buildManifest(...)`;
+- generated Worker manifest JSON;
+- warning text if a channel needs hosted bindings that the current artifact cannot run yet.
+
+The generated Worker should not perform real channel processing until ingress/queue tasks land, but the manifest must carry enough metadata for the control plane to create resources.
+
+Tests belong in `packages/agentkit/src/runtime/build.test.ts`.
+
+## New Runtime Modules
+
+Add `packages/agentkit/src/runtime/channels.ts` for normalized types and registry-level helpers.
+
+It should own:
+
+- `RawWebhookEvent`;
+- `NormalizedChannelEvent`;
+- `NormalizedChannelMessage`;
+- `ChannelAdapter`;
+- `ChannelSendInput`;
+- `ChannelSendResult`;
+- `WebhookVerificationInput`;
+- `WebhookVerificationResult`;
+- `ChannelStatusInput`;
+- `ChannelStatusResult`;
+- adapter lookup by channel type/provider;
+- shared secret redaction helpers if they are not already generic.
+
+Add adapter modules under `packages/agentkit/src/runtime/channels/`:
+
+- `website.ts`;
+- `telegram.ts`;
+- `whatsapp-zapster.ts`;
+- `whatsapp-meta.ts` as a compatibility stub.
+
+Add fixtures under `packages/agentkit/src/runtime/fixtures/channels/`:
+
+- `website-message.json`;
+- `telegram-message.json`;
+- `telegram-unsupported-update.json`;
+- `zapster-message.json`;
+- `zapster-unsupported-media.json`;
+- duplicate-event variants where useful.
+
+Default tests must use these fixtures and fake fetchers only.
+
+## CLI Entry Points
+
+Edit `packages/agentkit/src/cli/index.ts` only after config/build/control-plane basics exist.
+
+Add a `channels` command with subcommands:
+
+- `list`;
+- `add`;
+- `setup`;
+- `status`;
+- `test`;
+- `deliveries list`;
+- `deliveries show`.
+
+Keep command behavior split:
+
+- Before deploy: read local capsule config and explain missing deploy/setup state.
+- After deploy: read `.agentkit/deploy.json` and call the AgentKit Cloud API.
+
+Do not make the CLI mutate real Telegram/Zapster settings in default tests. Provider mutations need explicit credentials and opt-in smoke gates.
+
+## Control Plane
+
+Edit `packages/agentkit/src/runtime/deploy.ts` after manifest and CLI contracts are clear.
+
+Current control-plane API only serves:
+
+- `GET /health`;
+- `POST /v1/deploys`.
+
+Add:
+
+- `POST /v1/deploys/{deploy_id}/channels`;
+- `GET /v1/deploys/{deploy_id}/channels`;
+- `GET /v1/channels/{channel_id}`;
+- `DELETE /v1/channels/{channel_id}`;
+- public webhook routes for `/channels/{channel_id}/{type}/{provider}/webhook`;
+- delivery inspection routes for CLI use.
+
+The local `npm run agentkit:operator -- serve` path can use an in-memory or local SQLite fake store first. Production Postgres support can follow once the contract is tested. In both stores, persist only secret names and statuses, never secret values.
+
+## Hosted Worker And Cloudflare Bindings
+
+Edit `packages/agentkit/src/runtime/targets/cloudflare/build.ts` when adding real hosted ingress.
+
+The Worker currently handles:
+
+- `GET /_agentkit`;
+- `GET /`;
+- `POST /chat`;
+- Turso health/query helpers;
+- R2 file routes.
+
+Channels will need:
+
+- a channel ingress route;
+- raw body preservation for verification;
+- a channel coordination Durable Object for dedupe and identity mapping;
+- Cloudflare Queue producer and consumer bindings;
+- delivery state persistence or calls back to AgentKit Cloud;
+- redaction-aware logs.
+
+Do not put AgentKit channel plumbing in the user's Turso database. Turso remains only for the user's agent application tables.
+
+## Storage Boundary Decision
+
+For local tests, use the AgentKit Cloud fake/control-plane store for channel resource metadata and delivery records.
+
+Use this boundary for V1 local cloud tests:
+
+| Record | Local `npm run agentkit:operator -- serve` store | Generated Worker / Durable Object / Queue contract |
+| --- | --- | --- |
+| Channel resource metadata | Yes: `channels` table or equivalent fake store keyed by `chn_...`. | Read-only manifest input after deploy. |
+| Channel secret references | Yes: names and `set`/`missing` status only. | Runtime receives injected secret values by name; no readback. |
+| Channel endpoint URL | Yes: generated from deploy URL plus stable channel ID. | Worker routes requests by channel ID, type, and provider. |
+| Channel delivery records | Yes: `deliveries` table keyed by `del_...` for CLI inspection. | Worker/consumer reports state transitions back to control plane or durable storage. |
+| Channel event audit records | Yes: compact event records keyed by `chevt_...`, with redacted provider metadata. | Ingress creates or reports event records after provider validation. |
+| External identity mappings | Fake DO-compatible store for local tests, keyed by `chid_...`. | Durable Object owns strongly consistent identity to conversation mapping. |
+| Dedupe keys | Fake DO-compatible store with default 14-day retention. | Durable Object owns deterministic dedupe keys and retention. |
+| Per-conversation ordering/backpressure | Fake DO-compatible store only when tests need it. | Durable Object owns locks and short-lived backpressure state. |
+| Queue payloads | In-memory fake queue drained by tests. | Cloudflare Queue owns async ingress to consumer handoff. |
+| Raw payload/media blobs | Do not persist by default in local tests; use fixtures. | R2 stores large raw payloads, media, exports, and debug bundles. |
+| User application data | Never. | Never. User application tables stay in Turso. |
+
+Use Durable Object-compatible abstractions for:
+
+- dedupe keys;
+- external identity to conversation ID mappings;
+- ordering/backpressure state.
+
+This keeps the implementation aligned with the production architecture while allowing deterministic tests without real Cloudflare bindings.
+
+The first implementation should prefer an in-memory fake store for tests unless persistence across local control-plane restarts is being tested. Production Postgres can mirror the same resource/delivery tables later, after API behavior is stable.
+
+## Implementation Order
+
+Start with the unblocked tasks from `TASKS.md`:
+
+1. CH-01: decide the final local fake store shape.
+2. CH-02: add public channel config helpers.
+3. CH-03: validate `channels` config.
+4. CH-04: include channels in inspect/build manifests.
+5. CH-05 and CH-06: add normalized runtime types and fixture-first adapter tests.
+
+Do not begin channel CRUD or ingress until CH-04 exists. The control plane needs channel metadata in the build manifest, otherwise hosted resources are disconnected from the deploy artifact.
+
+## Test Strategy
+
+Default verification should stay offline:
+
+```sh
+bun test
+npm run typecheck
+```
+
+Provider tests should be opt-in:
+
+```sh
+AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
+AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
+```
+
+Real-provider smoke tests must document required secret names and must never print secret values.

package/docs/guides/create-agent.md

@@ -19,7 +19,6 @@ cd /tmp/agentkit-demo
 
 npx @andreprado/agentkit@alpha new demo --template blank
 cd demo
-npm install
 npm run typecheck
 npm run chat -- --message "hello"
 npm run agentkit -- conversations list
@@ -37,7 +36,6 @@ For the support template:
 ```sh
 npx @andreprado/agentkit@alpha new support-demo --template support
 cd support-demo
-npm install
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 ```
 
@@ -86,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.
+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.
 
 Optional shortcut when copying a prompt into another coding agent:
 
@@ -137,6 +135,27 @@ Expected chat output:
 Echo: 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.
+
+`test/fake` is deterministic. It validates the scaffold, 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.
+
 ## Safety Rules
 
 - Do not commit `.env`.
@@ -173,7 +192,7 @@ npm install
 npm run typecheck
 ```
 
-Make sure `tsconfig.json` has `moduleResolution: "Bundler"`.
+`agentkit new` installs dependencies by default. Run this if the scaffold was created with `--no-install`, the install failed, or `node_modules` was deleted. Make sure `tsconfig.json` has `moduleResolution: "Bundler"`.
 
 `No agentkit.config.ts found`:
 

package/docs/guides/prepare-deploy.md

@@ -19,7 +19,6 @@ Use this before asking a coding agent to make a capsule deployable, or before te
 From the capsule root:
 
 ```sh
-npm install
 npm run typecheck
 npm run agentkit -- inspect
 npm run agentkit -- db migrate
@@ -31,8 +30,9 @@ All scaffold, local dev, chat, eval, inspect, database, and build commands are t
 ```sh
 npm run agentkit -- login --token agk_user_...
 npm run agentkit -- deploy doctor
-npm run agentkit -- secret set OPENAI_API_KEY sk-...
-npm run agentkit -- deploy
+npm run agentkit -- secret set OPENAI_API_KEY --from-local-env
+npm run agentkit -- deploy --smoke "hello"
+npm run agentkit -- chat-ui --deploy
 ```
 
 If the capsule uses OpenAI locally, put the user’s local key in `.env`:
@@ -126,12 +126,18 @@ For a final end-to-end test, run:
 
 ```sh
 npm run agentkit -- login --token agk_user_...
+npm run agentkit -- secret sync --from-local
 npm run agentkit -- secret list
-npm run agentkit -- deploy
+npm run agentkit -- deploy --smoke "hello"
 npm run agentkit -- deploy status
+npm run agentkit -- chat-ui --deploy
 npm run agentkit -- access token list
 ```
 
+For private hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json`. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
+
+When the UI is running, open the printed `Chat:` URL and tell the owner the exact URL. If the capsule is still on `test/fake`, say the UI was tested only with the deterministic fake provider.
+
 ## Readiness Checklist
 
 ```txt
@@ -169,7 +175,13 @@ Missing hosted secret:
 Set the secret in AgentKit Cloud or the configured control plane:
 
 ```sh
-npm run agentkit -- secret set OPENAI_API_KEY sk-...
+npm run agentkit -- secret set OPENAI_API_KEY --from-local-env
+```
+
+To sync all declared user-managed secrets present in local `.env`:
+
+```sh
+npm run agentkit -- secret sync --from-local
 ```
 
 Do not write hosted secret values into the capsule.
@@ -180,7 +192,7 @@ Before a hosted production deploy, run:
 npm run agentkit -- deploy doctor
 ```
 
-The doctor checks AgentKit Cloud login, alpha deploy entitlement, declared hosted secrets, local `.env` names that have not been uploaded with `agentkit secret set`, and private-access runtime token handling. `agentkit deploy` runs the same readiness check automatically before building and uploading the artifact.
+The doctor checks AgentKit Cloud login, alpha deploy entitlement, online deploy capacity, declared hosted secrets, local `.env` names that have not been uploaded with `agentkit secret set`, and private-access runtime token handling. `agentkit deploy` runs the same readiness check automatically before building and uploading the artifact.
 
 `alpha_access_required`:
 

package/docs/guides/run-evals.md

@@ -84,12 +84,38 @@ export default {
 
 `tool_call` remains accepted as a backwards-compatible alias, but new evals should use `persisted_tool_call`.
 
+Safe external-tool pattern:
+
+```ts
+export const sendFollowupEmail = defineTool({
+  name: "send_followup_email",
+  description: "Sends a follow-up email.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      email: { type: "string" },
+    },
+    required: ["email"],
+    additionalProperties: false,
+  },
+  async execute(input: { email: string }, ctx) {
+    if (ctx.runtime.environment === "eval") {
+      return { sent: false, evalFixture: true, email: input.email };
+    }
+
+    // Real provider call here.
+    return { sent: true, evalFixture: false, email: input.email };
+  },
+});
+```
+
 ## Safety Rules
 
 - Do not put provider keys in eval files.
 - Do not put real client PII in eval files.
 - Prefer small deterministic assertions.
-- Mock tools for evals that would write, delete, charge money, or email people.
+- Keep eval tool calls deterministic and non-destructive.
+- For tools that would write, delete, charge money, send email, or call a real customer system, branch inside the registered tool on `ctx.runtime.environment === "eval"` and return safe fixture output.
 - Treat conversations as source material, not as automatically safe training data.
 
 ## Verification
@@ -111,7 +137,7 @@ Use `test/fake` for deterministic smoke tests, then add provider-specific evals
 
 Tool eval hits a real API:
 
-Add tool mocks before running the eval suite.
+Make the registered tool return deterministic fixture output when `ctx.runtime.environment === "eval"`, then rerun the eval suite. AgentKit does not expose a separate eval-only mock registry yet.
 
 ## Backend Contracts Used
 

package/docs/guides/security-rules.md

@@ -29,7 +29,7 @@ Hosted alpha secret commands:
 
 ```sh
 agentkit login --token agk_user_...
-agentkit secret set OPENAI_API_KEY
+agentkit secret set OPENAI_API_KEY --from-local-env
 agentkit secret list
 agentkit secret unset OPENAI_API_KEY
 ```

package/docs/guides/use-provider.md

@@ -6,7 +6,9 @@ Switch a capsule from the offline `test/fake` provider to a Pi-backed provider.
 
 ## When To Use This
 
-Use this when local fake responses are no longer enough and the agent needs model behavior from OpenAI, Anthropic, or OpenRouter.
+Use this when local fake responses are no longer enough and the agent needs model behavior from OpenRouter, OpenAI, Anthropic, or another supported provider.
+
+The coding agent should not choose a real provider automatically. Ask the owner which provider to use, then update the capsule.
 
 ## Commands
 
@@ -75,6 +77,17 @@ provider: {
 secrets: ["OPENROUTER_API_KEY"],
 ```
 
+## UI Verification
+
+After the provider is configured and the local secret is set, test through chat and UI:
+
+```sh
+npm run chat -- --message "hello"
+npm run dev
+```
+
+Open the printed `Chat:` URL and tell the owner the exact URL. If the provider is still `test/fake`, say the UI was tested only with the deterministic fake provider.
+
 ## Safety Rules
 
 - Keep `.env` local.
@@ -84,6 +97,7 @@ secrets: ["OPENROUTER_API_KEY"],
 - Do not import provider SDKs in the Agent Capsule.
 - AgentKit uses Pi SDK internally.
 - Run `agentkit inspect` to confirm secret status without printing values.
+- Do not claim real conversation behavior was tested until a real provider selected by the owner is configured.
 
 ## Verification
 
@@ -123,4 +137,4 @@ Check the key value, provider account status, and model access.
 
 ## Backend Contracts Used
 
-Local provider keys come from ignored `.env`, loaded directly by AgentKit. Hosted production will use `agentkit secret set <NAME>` and the secret API. Secret values have no readback in hosted responses.
+Local provider keys come from ignored `.env`, loaded directly by AgentKit. Hosted production uses `agentkit secret set <NAME> --from-local-env`, `--from-env`, or `--stdin` and the secret API. Secret values have no readback in hosted responses.