@andreprado/agentkit 0.1.1 → 0.3.0

package/docs/guides/run-evals.md

@@ -39,10 +39,10 @@ agentkit eval from-conversation <conversation-id>
 agentkit eval run
 ```
 
-Create evals from hosted or local production evidence:
+Create evals from local production evidence:
 
 ```sh
-agentkit improve collect --deploy --since 24h
+agentkit improve collect --since 24h
 agentkit improve evals .agentkit/improve/<run>
 agentkit replay .agentkit/improve/<run> --against local
 agentkit eval run
@@ -245,5 +245,3 @@ Tool eval hits a real API:
 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
-
-Future hosted evals use `EvalCase` and `EvalResult` resources. The current local implementation stores conversations, messages, runs, and tool calls only.

package/docs/guides/security-rules.md

@@ -1,160 +1,11 @@
 # Security Rules
 
-## Goal
+Keep secret values in ignored `.env`; commit only names in `.env.schema` and config. Use `agentkit env set <NAME> --stdin` or `--from-env`, and inspect secret status with `agentkit inspect`. Provider OAuth credentials live outside capsules. Never print credentials or commit `.agentkit/`.
 
-Keep local and hosted AgentKit work from leaking secrets, exposing client data, or giving tools more power than they need.
+Tools are trusted local TypeScript, not sandboxed code. Validate input/output schemas, declare scoped secret names, and use narrow permissions. Permissions ending in `:read` may run through model-driven chat; other declared permissions require direct invocation with `agentkit tool` after reviewing the exact input. Model-generated confirmation is not owner authorization.
 
-## When To Use This
+Guard external writes in evals with `ctx.runtime.environment === "eval"` and deterministic fixtures. Do not send real messages or modify external services from tests unless explicitly authorized.
 
-Use this before adding provider keys, tool secrets, external APIs, public access, deploys, or evals created from real conversations.
+Only authenticated channel webhook routes may accept an HTTPS tunnel. Keep dev UI, chat, tools, files, and conversation APIs loopback-only. Preserve provider signature checks, secret tokens, media URL restrictions, and outbound SSRF protection. See `docs/guides/channel-security.md`.
 
-## 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
-
-- An Agent Capsule is executable TypeScript. Run AgentKit commands only in Capsules whose config, tools, evals, and sync code you trust; AgentKit does not sandbox Capsule code from the local filesystem, network, or process environment.
-- `.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 deploys require `cloudflare_deploy_alpha` or purchased/manual deploy slots; 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.
-- Permissions ending in `:read` may run from chat, channels, and evals. Any other declared permission is operator-only and must be invoked directly with `agentkit tool <name> --input '<json>'` after reviewing the exact action.
-- Local dev access accepts only loopback Host/Origin values and limits JSON and webhook bodies to 1 MiB. Keep public tunnels behind authenticated access instead of weakening these checks.
-- Add timeouts to network tools.
-- Treat hosted deploy URLs as addresses, not access control.
-- Use deploy access tokens for hosted chat, hosted conversation reads, hosted trace reads, and any client app that talks to AgentKit Cloud.
-- Remove client PII before writing evals.
-- Review `.agentkit/feedback/` drafts before sending AgentKit product feedback. Do not paste `.env` values, provider keys, cookies, client PII, or full private transcripts into feedback messages.
-
-## 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
-```
-
-Hosted URL is reachable without a token:
-
-Treat this as a security bug. Hosted AgentKit Cloud routes should reject missing deploy tokens except authenticated channel webhook ingress.
-
-## 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.
+Review traces, improve bundles, and feedback drafts before sharing. They may contain customer data even after redaction. Rotate leaked credentials at their provider, then update the local value and check affected traces.

package/docs/guides/use-jev.md

@@ -12,7 +12,7 @@ Read the live [TypeSafe docs index](https://docs.typesafe.ai/llms.txt), [buildin
 - [Noul](https://docs.typesafe.ai/primitives/noul): estimate the probability of a yes/no condition. It has no separate confidence field.
 - [Score](https://docs.typesafe.ai/primitives/score): rate along concrete ordered levels.
 
-Use the closest cookbook from the index for the requested workflow. If the official `typesafe-ai` skill is installed, use it; it is optional and this workflow does not depend on a personal skill or helper being present. Check the current [HTTP contract](https://docs.typesafe.ai/api) when using the example, or the [JavaScript SDK](https://docs.typesafe.ai/sdk/javascript) if the capsule already uses it. Verify SDK compatibility with the capsule's deploy target before adding a dependency.
+Use the closest cookbook from the index for the requested workflow. If the official `typesafe-ai` skill is installed, use it; it is optional and this workflow does not depend on a personal skill or helper being present. Check the current [HTTP contract](https://docs.typesafe.ai/api) when using the example, or the [JavaScript SDK](https://docs.typesafe.ai/sdk/javascript) if the capsule already uses it. Verify SDK compatibility with the capsule's Node runtime before adding a dependency.
 
 ## Build The Requested Capability
 
@@ -37,17 +37,14 @@ Set the real value through the local secret prompt:
 npm run agentkit -- env set TYPESAFE_API_KEY
 ```
 
-Read it only from `ctx.secrets.TYPESAFE_API_KEY` inside the tool. For a hosted capsule, follow [Prepare Deploy](prepare-deploy.md) and upload the key through managed secrets:
+Read it only from `ctx.secrets.TYPESAFE_API_KEY` inside the tool. Keep the value in ignored local `.env`.
 
-```sh
-npm run agentkit -- secret set TYPESAFE_API_KEY --from-local-env
-```
 
 Send only the state needed for the judgment. Tool inputs and outputs are recorded, so avoid secrets, unnecessary client identifiers, and full conversation histories. Do not echo upstream response bodies or headers in errors. Forward `ctx.signal`, set a tool timeout, and validate returned values before using them. A timeout, 429, invalid response, or missing key must remain an explicit failure or a deliberately designed fallback; never turn it into a successful judgment.
 
 ## Verify
 
-The bundled example includes a fixture eval. In an isolated offline test capsule, supply a non-secret dummy `TYPESAFE_API_KEY`: AgentKit resolves declared secrets before entering the tool, even for eval fixtures. The fixture branch runs only in `eval` or `test`; `test/fake` as the conversational provider alone does not prevent live tool calls. Never upload a dummy key to a hosted capsule or substitute fixtures for production failures.
+The bundled example includes a fixture eval. In an isolated offline test capsule, supply a non-secret dummy `TYPESAFE_API_KEY`: AgentKit resolves declared secrets before entering the tool, even for eval fixtures. The fixture branch runs only in `eval` or `test`; `test/fake` as the conversational provider alone does not prevent live tool calls. Never substitute fixtures for real runtime failures.
 
 ```sh
 npm run typecheck

package/docs/guides/use-provider.md

@@ -49,12 +49,12 @@ To use the Codex subscription login instead of an OpenAI API key:
 npm run agentkit -- provider login openai-codex
 ```
 
-Run this in an interactive terminal, open the printed URL, and sign in with ChatGPT. If the browser callback cannot reach the terminal, paste the redirect URL into the prompt. This uses Pi's Codex OAuth flow and creates an AgentKit session; it does not read or change the Codex app/CLI credential cache.
+Run this in an interactive terminal, choose browser login (default) or device code login for headless machines, then sign in with ChatGPT. If the browser callback cannot reach the terminal, paste the redirect URL into the prompt. This uses Pi's Codex OAuth flow and creates an AgentKit session; it does not read or change the Codex app/CLI credential cache.
 
 Configure the capsule:
 
 ```ts
-provider: { name: "openai-codex", model: "gpt-5.4" },
+provider: { name: "openai-codex", model: "gpt-5.5" },
 secrets: [], // Keep any secrets required by your tools or other services.
 ```
 
@@ -68,7 +68,6 @@ npm run agentkit -- provider logout openai-codex
 
 `status` reports `logged_out`, `logged_in`, or `refresh_required` without token values. It checks the local cache, not account access at OpenAI. Local chat, dev, and eval renew expiring credentials through Pi automatically. Credentials live outside the capsule at `~/.agentkit/providers/openai-codex.json` with owner-only file permissions. The login is shared by local capsules under the same OS user. Logout removes this AgentKit session locally; it does not revoke the session at OpenAI or sign out the Codex app.
 
-This provider currently supports local execution only. Cloudflare, container, and VPS builds reject it with `target_runtime_incompatible`; choose an API-key provider and managed secrets for deployment. AgentKit never uploads the local OAuth session or falls back to API-key billing.
 
 If refresh fails, rerun login. If `provider_auth_busy` persists after a crashed process, stop AgentKit processes before removing the `.lock` directory next to the credential file, then retry.
 
@@ -103,7 +102,7 @@ Anthropic:
 ```ts
 provider: {
   name: "anthropic",
-  model: "claude-3-5-haiku-latest",
+  model: "claude-haiku-4-5",
 },
 secrets: ["ANTHROPIC_API_KEY"],
 ```
@@ -194,6 +193,8 @@ npm run agentkit -- inspect
 
 For OpenAI, Anthropic, OpenCode Zen, or OpenCode Go, use a model id known to the installed Pi SDK for that provider. For OpenRouter, prefer a known Pi alias when possible; otherwise a raw OpenRouter model id is passed through and any remaining model error comes from OpenRouter.
 
+After upgrading to AgentKit 0.3.0 (Pi 0.99), `openai-codex` no longer offers `gpt-5.4` or `gpt-5.4-mini`, and `anthropic` no longer offers `claude-3-5-haiku-latest`. Switch to a listed model such as `gpt-5.5` or `claude-haiku-4-5`; the error message lists examples.
+
 Provider returns auth failure:
 
 Check the key value, provider account status, and model access.
@@ -203,5 +204,3 @@ Check the key value, provider account status, and model access.
 `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.

package/docs/guides/write-feedback.md

@@ -0,0 +1,10 @@
+# Write AgentKit Feedback
+
+Create a local, redacted report when a command fails or documentation is unclear:
+
+```sh
+agentkit feedback create --about last-run --kind bug --summary "what failed"
+agentkit feedback preview .agentkit/feedback/<draft>.json
+```
+
+Drafts include current capsule metadata, not a saved last-command transcript. JSON and Markdown files stay under `.agentkit/feedback/` unless `--out` is specified. Review redaction before sharing them manually. AgentKit does not upload reports.