@andreprado/agentkit 0.1.0-alpha.10

package/docs/guides/security-rules.md

@@ -0,0 +1,156 @@
+# Security Rules
+
+## Goal
+
+Keep local and hosted AgentKit work from leaking secrets, exposing client data, or giving tools more power than they need.
+
+## When To Use This
+
+Use this before adding provider keys, tool secrets, external APIs, public access, deploys, or evals created from real conversations.
+
+## Commands
+
+Local checks:
+
+```sh
+git status --short
+npm run agentkit -- env list
+npm run agentkit -- inspect
+npm run typecheck
+```
+
+Search for accidental local secret files:
+
+```sh
+find . -maxdepth 3 \( -name .env -o -path './.agentkit/*' \) -print
+```
+
+Hosted alpha secret commands:
+
+```sh
+agentkit login --token agk_user_...
+agentkit secret set OPENAI_API_KEY --from-local-env
+agentkit secret list
+agentkit secret unset OPENAI_API_KEY
+```
+
+## Files Created Or Edited
+
+Allowed committed files:
+
+```txt
+.env.schema
+agentkit.config.ts
+prompts/
+tools/
+evals/
+AGENTS.md
+CLAUDE.md
+README.md
+```
+
+Never commit:
+
+```txt
+.env
+.agentkit/
+node_modules/
+```
+
+## Minimal Working Example
+
+Declare secret names:
+
+```ts
+export default defineAgent({
+  secrets: ["OPENAI_API_KEY"],
+});
+```
+
+Set local secret names in `.env.schema`, keep values in ignored `.env`, and run AgentKit commands normally:
+
+```sh
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+```
+
+Declare tool-specific secrets:
+
+```ts
+defineTool({
+  name: "lookup_customer",
+  secrets: ["CRM_API_KEY"],
+  permissions: ["crm:contacts:read"],
+  execute(input, ctx) {
+    return fetchCustomer(input, ctx.secrets.CRM_API_KEY);
+  },
+});
+```
+
+## Safety Rules
+
+- `.env` is local-only.
+- `.env.schema` is the committed contract for local secret names.
+- AgentKit local commands load `.env` directly so inspect, chat, tools, and evals share the same secret loader.
+- Production uses managed secrets.
+- Hosted alpha deploys require `cloudflare_deploy_alpha`; local commands do not require login.
+- Secret values must not appear in config, docs, prompts, evals, logs, exports, or SQLite.
+- A tool receives only secrets listed in that tool.
+- Avoid direct `process.env` reads inside tools.
+- Use `permissions` to describe external capabilities.
+- Add timeouts to network tools.
+- Treat public deploy URLs as unauthenticated transport, not access control.
+- Use access tokens and limits for clients.
+- Remove client PII before writing evals.
+
+## Verification
+
+```sh
+npm run agentkit -- inspect
+git status --short
+git diff --check
+```
+
+Expected:
+
+- Inspect shows secret names as `set` or `missing`.
+- Inspect does not show secret values.
+- `.env` and `.agentkit/` are untracked or ignored.
+- Tool calls persist without secret values.
+
+## Troubleshooting
+
+Secret value appears in a file:
+
+Remove it, rotate the provider key, and check git history before sharing the branch.
+
+Tool needs a secret but receives `{}`:
+
+Add the secret name to the tool `secrets` field and set it locally:
+
+```sh
+npm run agentkit -- inspect
+```
+
+Public URL is reachable:
+
+Check hosted access mode. Default should be `private`.
+
+## Backend Contracts Used
+
+Hosted secrets use:
+
+```txt
+PUT /v1/projects/{project_id}/secrets/{name}
+GET /v1/projects/{project_id}/secrets
+DELETE /v1/projects/{project_id}/secrets/{name}
+```
+
+Hosted access uses:
+
+```txt
+PATCH /v1/deploys/{deploy_id}/access
+POST  /v1/deploys/{deploy_id}/access-tokens
+```
+
+Backend responses never return secret values.

package/docs/guides/use-provider.md

@@ -0,0 +1,140 @@
+# Use A Real Provider
+
+## Goal
+
+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 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
+
+From a capsule root:
+
+```sh
+$EDITOR agentkit.config.ts
+npm run typecheck
+npm run chat -- --message "hello"
+npm run agentkit -- inspect
+```
+
+## Files Created Or Edited
+
+Edit:
+
+```txt
+agentkit.config.ts
+.env.schema
+.env
+```
+
+Use `.env.schema` as the committed contract for required names. Keep `.env` local and ignored.
+
+## Minimal Working Example
+
+OpenAI:
+
+```ts
+provider: {
+  name: "openai",
+  model: "gpt-4o-mini",
+},
+secrets: ["OPENAI_API_KEY"],
+```
+
+`.env.schema`:
+
+```sh
+OPENAI_API_KEY=
+```
+
+Run with local secrets loaded:
+
+```sh
+npm run chat -- --message "hello"
+```
+
+Anthropic:
+
+```ts
+provider: {
+  name: "anthropic",
+  model: "claude-3-5-haiku-latest",
+},
+secrets: ["ANTHROPIC_API_KEY"],
+```
+
+OpenRouter:
+
+```ts
+provider: {
+  name: "openrouter",
+  model: "gpt-4o-mini",
+},
+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.
+- Use `.env.schema` as the committed secret-name contract.
+- AgentKit local commands load `.env` directly so chat, evals, tools, and inspect use the same loader.
+- Add required provider secret names to `secrets`.
+- 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
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+```
+
+Expected:
+
+- Inspect shows the provider secret as `set`.
+- Chat returns a real model response.
+- `.agentkit/agentkit.db` stores messages and usage tokens when Pi returns usage.
+
+## Troubleshooting
+
+`secret_not_found`:
+
+Add the required provider key to ignored `.env`, keep the name in `.env.schema`, and rerun AgentKit.
+
+```sh
+npm run agentkit -- inspect
+```
+
+`provider_model_unsupported`:
+
+Use a model id known to the installed Pi SDK for that provider.
+
+Provider returns auth failure:
+
+Check the key value, provider account status, and model access.
+
+`custom` provider:
+
+`custom` is reserved in config but not implemented in the local adapter yet.
+
+## Backend Contracts Used
+
+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.