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

package/docs/llms-full.txt

@@ -30,54 +30,65 @@ The capsule root is the runtime boundary. Run AgentKit commands from the directo
 
 ## Current Command Surface
 
-Implemented local commands:
+Current commands:
 
 ```sh
-agentkit new <name> --template blank
-agentkit new <name> --template support
-agentkit chat --message "hello"
-agentkit tool <name> --input <path-or-json>
+agentkit new <name> [--template blank|support|dentista] [--no-install]
+agentkit dev [--port <number>]
+agentkit open
+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 db migrate
+agentkit db reset --yes
+agentkit db shell
+agentkit db seed [--file <path>]
 agentkit eval run
 agentkit conversations list
 agentkit conversations show <conversation-id>
 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 <name>
-agentkit channels setup <name> --apply
-agentkit channels status <name>
-agentkit channels test <name> --message "hello"
-agentkit channels test <name> --fixture ./fixtures/provider-event.json
-agentkit channels deliveries list <name>
-agentkit channels deliveries show <delivery-id>
+agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
+agentkit channels setup <name> [--apply] [--api <url>]
+agentkit channels status <name> [--api <url>]
+agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
+agentkit channels deliveries list <name> [--api <url>]
+agentkit channels deliveries show <delivery-id> [--api <url>]
 agentkit inspect
-agentkit env set <NAME> <VALUE>
-agentkit env list
-agentkit env unset <NAME>
-agentkit docs path
-agentkit docs llms
-agentkit docs full
-agentkit handoff codex [goal]
-agentkit handoff claude [goal]
-agentkit dev
-agentkit dev --port 4124
-agentkit build
-agentkit deploy
-agentkit deploy --dry-run
+agentkit build [--target cloudflare|container]
 agentkit login --token <token>
 agentkit logout
+agentkit deploy [--target cloudflare|vps] [--host <host>] [--api <url>] [--dry-run] [--anonymous] [--local-wrangler] [--smoke <message>]
+agentkit deploy doctor [--api <url>] [--anonymous]
+agentkit deploy smoke [--message <text>] [--api <url>]
 agentkit deploy status
 agentkit deploy pause
 agentkit deploy resume
 agentkit secret set <NAME> <VALUE>
+agentkit secret set <NAME> --stdin
+agentkit secret set <NAME> --from-env [ENV_NAME]
+agentkit secret set <NAME> --from-local-env
+agentkit secret sync --from-local
 agentkit secret list
 agentkit secret unset <NAME>
-agentkit access token create <name>
+agentkit access token create <name> [--api <url>] [--out <path>]
 agentkit access token list
 agentkit access token revoke <token-id>
+agentkit env set <NAME> <VALUE>
+agentkit env set <NAME> --stdin
+agentkit env set <NAME> --from-env [ENV_NAME]
+agentkit env list
+agentkit env unset <NAME>
+agentkit docs path
+agentkit docs llms
+agentkit docs full
+agentkit handoff codex [goal]
+agentkit handoff claude [goal]
+agentkit help commands
 ```
 
+Prefer `env set --stdin` or `--from-env` for local secret values, and prefer `secret set --stdin`, `--from-env`, or `--from-local-env` for hosted secrets. Inline `<VALUE>` forms exist for simple non-sensitive values, but agents should avoid putting secrets in shell history.
+
 Planned commands described by the contract but not implemented yet:
 
 ```sh
@@ -95,7 +106,6 @@ cd /tmp/agentkit-demo
 
 npx @andreprado/agentkit@alpha new demo --template blank
 cd demo
-npm install
 npm run chat -- --message "hello"
 npm run chat -- --message "second message"
 npm run eval
@@ -117,7 +127,6 @@ The primary flow is:
 ```sh
 agentkit new eye-office-agent --template blank
 cd eye-office-agent
-npm install
 ```
 
 Then open the folder in Codex, Claude Code, or another coding agent and ask directly:
@@ -126,7 +135,7 @@ Then open the folder in Codex, Claude Code, or another coding agent and ask dire
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, and `tools/`, then run the verification commands before finishing.
+The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, `schema.sql`, `tools/`, and `evals/`, then run the verification commands before finishing. Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; the coding agent implements directly in the capsule.
 
 Optional handoff shortcut:
 
@@ -137,6 +146,8 @@ npm run agentkit -- handoff claude "Develop an appointment and intake agent for
 
 The command prints a ready-to-paste prompt that points the coding agent at `AGENTKIT.md` and the packaged `llms-full.txt` 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.
+
 ## Agent Config
 
 `agentkit.config.ts` is the source of truth:
@@ -203,7 +214,11 @@ provider: {
 secrets: [],
 ```
 
-Use OpenAI locally:
+`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 has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them. After the owner chooses, update `agentkit.config.ts`, `.env.schema`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
+
+OpenAI example:
 
 ```ts
 provider: {
@@ -540,6 +555,8 @@ Run:
 agentkit dev
 ```
 
+If the default local port is occupied, `agentkit dev` chooses the next available port and prints the actual URLs. If the occupied port is another AgentKit server, the output names the agent using it.
+
 Expected output:
 
 ```txt
@@ -551,6 +568,12 @@ Inspect:   http://localhost:4123/_agentkit
 Storage:   .agentkit/agentkit.db
 ```
 
+To reopen the local UI for the current capsule after the server is already running:
+
+```sh
+agentkit open
+```
+
 Endpoints:
 
 ```txt
@@ -568,6 +591,8 @@ curl -X POST http://localhost:4123/v1/chat \
   -d '{"message":{"role":"user","content":"hello"}}'
 ```
 
+The chat response includes `conversationId`. Send the same `conversationId` on the next `POST /v1/chat` request, or pass it to `agentkit chat --conversation-id <id>`, to continue with the persisted message history.
+
 ## Conversations
 
 After chat:
@@ -611,6 +636,8 @@ 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`. `tool_call` remains accepted as a backwards-compatible alias.
 
+Evals run the normal capsule tools. If a tool would write externally, delete, charge money, send email, or call a real customer system, make its `execute` implementation branch on `ctx.runtime.environment === "eval"` and return deterministic non-destructive output for eval runs. Do not invent an eval-only mock API; keep the behavior inside the registered tool contract unless AgentKit adds a first-class mock facility later.
+
 ## Security Rules
 
 Never commit:
@@ -634,7 +661,7 @@ prompts/
 docs/
 ```
 
-Local `.env` is development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted alpha deploys use `agentkit login --token ...` and managed secrets through `agentkit secret set/list/unset`.
+Local `.env` is development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted alpha deploys use `agentkit login --token ...` and managed secrets through `agentkit secret set/list/unset` or `agentkit secret sync --from-local`. Prefer `--stdin`, `--from-env`, `--from-local-env`, or sync from local `.env` so secret values do not appear in shell history. Inline `<VALUE>` forms exist only for compatibility and simple non-sensitive values.
 
 Tools are a security boundary. A tool must declare every secret it needs. The runtime injects only tool-declared secrets.
 
@@ -648,20 +675,23 @@ Current flow:
 agentkit deploy --dry-run
 agentkit login --token agk_user_...
 agentkit deploy doctor
-agentkit deploy
+agentkit deploy --smoke "hello"
 agentkit deploy status
+agentkit deploy smoke --message "hello"
+agentkit chat-ui --deploy
 ```
 
-`agentkit deploy doctor` checks AgentKit Cloud login, `cloudflare_deploy_alpha`, hosted secrets, local `.env` names that still need `agentkit secret set`, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud and runs the same readiness check automatically before building and uploading. Production alpha deploys require an account with `cloudflare_deploy_alpha`; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
+`agentkit deploy doctor` checks AgentKit Cloud login, `cloudflare_deploy_alpha`, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, and writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json` for private hosted deploys. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code. Production alpha deploys require an account with `cloudflare_deploy_alpha`; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
 
 The CLI defaults to the hosted AgentKit Cloud API at `https://agentkit-cloud.aibuilders.com.br`. Use `AGENTKIT_CLOUD_API_URL` or `agentkit deploy --api <url>` only for local or alternate control-plane tests.
 
 Account/access flow:
 
 ```sh
-agentkit secret set OPENAI_API_KEY
+agentkit secret set OPENAI_API_KEY --from-local-env
+agentkit secret sync --from-local
 agentkit secret list
-agentkit access token create website-chat
+agentkit access token create website-chat --out .agentkit/website-chat-access-token.json
 agentkit access token list
 ```
 
@@ -710,6 +740,8 @@ npm install
 npm run typecheck
 ```
 
+`agentkit new` installs dependencies by default. Run this if the scaffold used `--no-install`, the install failed, or `node_modules` was deleted.
+
 Make sure `tsconfig.json` contains:
 
 ```json

package/docs/llms.txt

@@ -24,8 +24,10 @@ Task guides:
 Current local commands:
 
 ```sh
-agentkit new <name> --template blank|support
+agentkit new <name> --template blank|support|dentista
+agentkit new <name> --template blank --no-install
 agentkit docs full
+agentkit env set <NAME> --stdin
 agentkit env list
 agentkit env unset <NAME>
 agentkit handoff codex|claude [goal]
@@ -42,16 +44,25 @@ agentkit channels test support-telegram --message "hello"
 agentkit channels deliveries list support-telegram
 agentkit login --token agk_user_...
 agentkit deploy doctor
-agentkit deploy
+agentkit deploy --smoke "hello"
 agentkit deploy status
+agentkit deploy smoke --message "hello"
+agentkit chat-ui --deploy
+agentkit secret set <NAME> --from-local-env
+agentkit secret sync --from-local
 agentkit secret list
-agentkit access token create website-chat
+agentkit access token create website-chat --out .agentkit/website-chat-access-token.json
 agentkit access token list
 agentkit inspect
 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.
+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.
+
+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.
+
+`test/fake` is deterministic and validates scaffold, direct tool calls, and fake-provider evals. It does not validate natural conversation quality. 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.
 
 Current local endpoints from `agentkit dev`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "private": false,
   "type": "module",
   "repository": {
@@ -36,7 +36,6 @@
     "@earendil-works/pi-ai": "^0.75.5",
     "@earendil-works/pi-coding-agent": "^0.75.5",
     "esbuild": "^0.28.0",
-    "postgres": "^3.4.9",
     "tsx": "^4.22.3",
     "typebox": "^1.1.38"
   },