@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

package/docs/guides/security-rules.md

@@ -89,19 +89,23 @@ defineTool({
 
 ## 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 alpha deploys require `cloudflare_deploy_alpha`; local commands do not require login.
+- 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 public deploy URLs as unauthenticated transport, not access control.
-- Use access tokens and limits for clients.
+- 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
 
@@ -132,9 +136,9 @@ Add the secret name to the tool `secrets` field and set it locally:
 npm run agentkit -- inspect
 ```
 
-Public URL is reachable:
+Hosted URL is reachable without a token:
 
-Check hosted access mode. Default should be `private`.
+Treat this as a security bug. Hosted AgentKit Cloud routes should reject missing deploy tokens except authenticated channel webhook ingress.
 
 ## Backend Contracts Used
 

package/docs/guides/send-feedback.md

@@ -0,0 +1,135 @@
+# Send Feedback To AgentKit
+
+## Goal
+
+Create a redacted local feedback draft when AgentKit itself is confusing, missing docs, or failing, then send it to AgentKit Cloud only after the user has authenticated.
+
+## When To Use This
+
+Use this for AgentKit product feedback, not for the user's agent's client conversations.
+
+Good cases:
+
+- an AgentKit CLI command failed and the error did not explain recovery;
+- a docs guide or generated skill is missing a step;
+- deploy, channel, provider, eval, or runtime behavior looks like an AgentKit bug;
+- the user's coding agent found a feature gap in AgentKit itself.
+
+Do not use this to upload private client data, provider keys, `.env` values, or full conversation transcripts.
+
+## Commands
+
+Create a local draft only:
+
+```sh
+agentkit feedback create --about last-run --kind bug --summary "Deploy failed after secrets sync"
+```
+
+Preview a draft:
+
+```sh
+agentkit feedback preview .agentkit/feedback/<draft>.json
+```
+
+Send a saved draft:
+
+```sh
+agentkit login --token agk_user_...
+agentkit feedback send .agentkit/feedback/<draft>.json
+```
+
+Create and send in one command:
+
+```sh
+agentkit feedback send --about deploy --kind deploy_issue --summary "Deploy doctor passed but deploy failed" --message "The recovery step was unclear."
+```
+
+## Files Created Or Edited
+
+`feedback create` writes ignored local files:
+
+```txt
+.agentkit/feedback/<timestamp>-<summary>.json
+.agentkit/feedback/<timestamp>-<summary>.md
+```
+
+These files are local diagnostic drafts. Keep `.agentkit/` out of commits.
+
+## Minimal Working Example
+
+```sh
+agentkit feedback create \
+  --about last-run \
+  --kind missing_docs \
+  --summary "The channel debug guide did not explain Discord bot mode recovery" \
+  --message "The command failed after setup, and I could not tell whether to rerun connect or setup."
+```
+
+Review the printed JSON path, then send it:
+
+```sh
+agentkit feedback send .agentkit/feedback/<draft>.json
+```
+
+## Safety Rules
+
+- Creating a draft never sends network feedback.
+- Sending requires AgentKit Cloud login.
+- The CLI redacts common bearer tokens, AgentKit tokens, provider key patterns, and Authorization headers before saving or sending.
+- AgentKit Cloud validates the payload again and stores the redacted report under the authenticated account.
+- Do not paste `.env` contents, provider key values, OAuth tokens, cookies, client PII, or full private transcripts into `--message`.
+- The feedback command does not upload arbitrary files and does not ask AgentKit Cloud to fetch URLs.
+- The deployed agent runtime does not send feedback to the AgentKit team.
+
+## Verification
+
+After creating a draft:
+
+```sh
+agentkit feedback preview .agentkit/feedback/<draft>.json
+```
+
+Expected:
+
+- `schema_version` is `agentkit.feedback.v1`;
+- `source.channel` is `cli`;
+- `context` describes the current capsule and deploy shape;
+- no secret values are present.
+
+After sending:
+
+```txt
+Feedback sent
+ID:     fb_...
+Status: new
+```
+
+## Troubleshooting
+
+`auth_required`:
+
+Log in before sending:
+
+```sh
+agentkit login --token agk_user_...
+```
+
+`feedback_draft_invalid`:
+
+Recreate the draft with `agentkit feedback create`. Do not hand-edit the JSON schema unless you keep `schema_version: "agentkit.feedback.v1"`.
+
+`payload_too_large`:
+
+Shorten `--message`. Do not paste full logs; include the command, exact error code, and the smallest useful excerpt.
+
+## Backend Contracts Used
+
+Feedback submit uses authenticated AgentKit Cloud account auth:
+
+```txt
+POST /v1/feedback
+Authorization: Bearer agk_user_...
+Idempotency-Key: fbdraft_...
+```
+
+The endpoint accepts only structured JSON feedback and stores it in the AgentKit Cloud feedback inbox.

package/docs/guides/use-jev.md

@@ -0,0 +1,67 @@
+# Use Jev In A Capsule Tool
+
+Use this when the owner asks their coding agent (Codex, Claude Code, or another agent) to build a capsule capability with TypeSafe/Jev, such as qualifying leads, ranking candidates, selecting a handler, or checking evidence.
+
+Implement the requested behavior through the existing `defineTool` contract. Jev supplies typed judgments inside the tool; the capsule's conversational provider continues through AgentKit. Keep questions and business criteria in the tool code, shaped by the owner's brief. No special AgentKit provider, runtime hook, or globally enabled Jev tool is needed.
+
+## Read The Relevant TypeSafe Guidance
+
+Read the live [TypeSafe docs index](https://docs.typesafe.ai/llms.txt), [building guide](https://docs.typesafe.ai/concepts/how-to-build-with-system-one), and the relevant primitive before designing the judgment:
+
+- [Choice](https://docs.typesafe.ai/primitives/choice): select from defined alternatives; include “none” or “insufficient evidence” when appropriate.
+- [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.
+
+## Build The Requested Capability
+
+1. Inspect the capsule's tools, config, prompts, and evals. Reuse an existing domain tool when Jev belongs inside its workflow.
+2. Adapt `skills/agentkit-tools/examples/jev-service-fit.tool.md` into `tools/<name>.ts`. The example uses native `fetch`, so no TypeSafe package is required. Register the export in the existing `agentkit.config.ts` tools array without replacing other config.
+3. Define narrow questions against relevant state: the client's request, available candidates, service definitions, or supporting evidence. Question IDs are only lookup keys; include the question's meaning in its instructions. Batch independent questions over the same state; sequence calls only when a later question needs an earlier result.
+4. Keep exact calculations, lookups, permission checks, and execution in code. Jev's output is evidence for a decision, never authorization for an external action. Preserve any existing tool permission requirements.
+5. Update `prompts/instructions.md` with when to call the tool and how to handle uncertain results or service failures. For the example, assess service fit before recommending the website service; ask for clarification when evidence is ambiguous, and do not treat a fit score as a quote, booking, or approval.
+6. Add deterministic checks and a persisted tool-call eval. Test the owner's actual criteria separately with labeled examples before choosing operational thresholds. [Confidence](https://docs.typesafe.ai/confidence) measures distribution concentration, not guaranteed correctness; a Noul near 0.5 represents uncertainty about yes/no, not medium intensity.
+
+## Secrets And External Data
+
+Declare `TYPESAFE_API_KEY` in the tool's `secrets` array and add the name with an empty value to `.env.schema`:
+
+```dotenv
+TYPESAFE_API_KEY=
+```
+
+Set the real value through the local secret prompt:
+
+```sh
+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:
+
+```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.
+
+```sh
+npm run typecheck
+npm run eval
+npm run agentkit -- inspect
+```
+
+For a live check with the real key, use synthetic data:
+
+```sh
+npm run agentkit -- tool assess_service_fit --input '{"message":"I need a website for my bakery."}'
+npm run agentkit -- conversations list
+```
+
+Expect a probability between 0 and 1 and `evalFixture: false`; inspect the recorded call without exposing the key. The fixture verifies wiring, not Jev's accuracy. Also test invalid inputs, unavailable service, malformed responses, and cancellation with mocked HTTP responses. Measure actual quality, latency, and cost before expanding usage.
+
+New capsules receive the example automatically. Existing capsules can update AgentKit and run `npm run agentkit -- skills sync` to refresh bundled skills; preserve any local skill edits before syncing.

package/docs/guides/use-provider.md

@@ -6,7 +6,7 @@ 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.
+Use this when local fake responses are no longer enough and the agent needs model behavior from OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, 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.
 
@@ -21,6 +21,14 @@ npm run chat -- --message "hello"
 npm run agentkit -- inspect
 ```
 
+On Windows PowerShell, if `npm.ps1` is blocked by `PSSecurityException`, use the Windows command shim:
+
+```sh
+npm.cmd run typecheck
+npm.cmd run chat -- --message "hello"
+npm.cmd run agentkit -- inspect
+```
+
 ## Files Created Or Edited
 
 Edit:
@@ -33,6 +41,39 @@ agentkit.config.ts
 
 Use `.env.schema` as the committed contract for required names. Keep `.env` local and ignored.
 
+## ChatGPT / Codex Login (Local)
+
+To use the Codex subscription login instead of an OpenAI API key:
+
+```sh
+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.
+
+Configure the capsule:
+
+```ts
+provider: { name: "openai-codex", model: "gpt-5.4" },
+secrets: [], // Keep any secrets required by your tools or other services.
+```
+
+Use a model supported by the installed Pi SDK for `openai-codex`. Remove `OPENAI_API_KEY` from `secrets` and `.env.schema` only if no other capability (such as embeddings or transcription) needs it. No provider key or OAuth token belongs in `.env` or capsule files for this login.
+
+```sh
+npm run agentkit -- provider status openai-codex
+npm run chat -- --message "hello"
+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.
+
+OpenAI documents subscription sign-in and API-key billing as separate authentication methods: [Codex authentication](https://learn.chatgpt.com/docs/auth).
+
 ## Minimal Working Example
 
 OpenAI:
@@ -77,6 +118,32 @@ provider: {
 secrets: ["OPENROUTER_API_KEY"],
 ```
 
+Prefer model ids or aliases listed by the installed Pi SDK when available, such as `~google/gemini-flash-latest`. If an OpenRouter model id is newer than the Pi model registry, AgentKit passes the id through to OpenRouter using Pi's OpenAI-compatible transport with conservative unknown-model metadata. The provider may still reject the request if the id is invalid, inaccessible, or does not support the tools/features the agent uses.
+
+OpenCode Zen:
+
+```ts
+provider: {
+  name: "opencode",
+  model: "big-pickle",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Zen model id listed by the installed Pi SDK, such as `big-pickle`, `deepseek-v4-flash-free`, `claude-sonnet-4-5`, or `gpt-5.4-mini`. OpenCode Zen uses `OPENCODE_API_KEY`.
+
+OpenCode Go:
+
+```ts
+provider: {
+  name: "opencode-go",
+  model: "deepseek-v4-flash",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Go model id listed by the installed Pi SDK, such as `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.1`, `kimi-k2.6`, `minimax-m2.7`, or `qwen3.6-plus`. OpenCode Go also uses `OPENCODE_API_KEY`.
+
 ## UI Verification
 
 After the provider is configured and the local secret is set, test through chat and UI:
@@ -109,7 +176,7 @@ npm run chat -- --message "hello"
 
 Expected:
 
-- Inspect shows the provider secret as `set`.
+- For API-key providers, inspect shows the provider secret as `set`; for Codex, use `provider status openai-codex`.
 - Chat returns a real model response.
 - `.agentkit/agentkit.db` stores messages and usage tokens when Pi returns usage.
 
@@ -125,7 +192,7 @@ npm run agentkit -- inspect
 
 `provider_model_unsupported`:
 
-Use a model id known to the installed Pi SDK for that provider.
+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.
 
 Provider returns auth failure: