@andreprado/agentkit 0.1.0-alpha.24 → 0.1.0-alpha.26

package/README.md

@@ -24,12 +24,15 @@ Generated capsules use the built-in `test/fake` provider by default, so the firs
 ## What To Know First
 
 ```sh
-agentkit new <name> [--template blank|support|dentista] [--no-install]
+agentkit new [name] [--template blank|support|dentista] [--no-install]
+agentkit new .
 agentkit dev
 agentkit chat --message <text> [--conversation-id <id>]
 agentkit inspect
 ```
 
+Run `agentkit new` without a name in an interactive terminal to be prompted for the project folder. Use `agentkit new .` to create the capsule in the current directory.
+
 Once the capsule is running:
 
 ```sh

package/docs/guides/add-managed-composio.md

@@ -114,9 +114,9 @@ googlecalendar: [
 
 ## Write Confirmation
 
-Managed Composio requires confirmation for external write actions by default. For actions such as create, update, delete, send, patch, move, insert, clear, remove, import, or quick add, the generated `agentkit_composio_execute` tool requires `confirmed: true`.
+Managed Composio requires operator invocation for external write actions. If an integration allows create, update, delete, send, patch, move, insert, clear, remove, import, or quick-add actions, AgentKit blocks that generated tool during model-driven chat, channel, and eval runs. Review the exact action and invoke `agentkit_composio_execute` directly with `agentkit tool`; write actions also require `confirmed: true` by default.
 
-Set `confirmed: true` only after the user confirms the exact external change. If a capsule intentionally handles confirmation elsewhere, disable this guard explicitly:
+`confirmExternalWrites: false` disables only Composio's secondary `confirmed` input check. It does not bypass AgentKit's operator-only permission boundary:
 
 ```ts
 composioManaged({

package/docs/guides/add-tool.md

@@ -8,6 +8,8 @@ Add a TypeScript tool to an Agent Capsule, register it in `agentkit.config.ts`,
 
 Use this when the agent needs to call code, read an API, query a database, or perform a small action behind a typed contract.
 
+For requests such as “use Jev to qualify leads” or “use TypeSafe to rank candidates,” follow [Use Jev](use-jev.md) and adapt the bundled tool example to the requested behavior.
+
 ## Commands
 
 From a capsule root:
@@ -265,6 +267,8 @@ Use it for diagnostics only, not for bypassing AgentKit runtime services or choo
 - Do not read arbitrary `process.env` inside tools.
 - Use `ctx.secrets.SECRET_NAME`.
 - Set `timeoutMs` for slow external calls.
+- End read-only permissions with `:read`, for example `crm:contacts:read`.
+- Declare writes, sends, deletes, payments, or broad external calls with a non-read permission such as `email:send`. AgentKit blocks those permissions during model-driven chat, channel, and eval runs; the local operator must review and invoke the exact call with `agentkit tool`.
 - Set `visibility: "internal"` for operational outputs such as classifications, scores, routing labels, fraud decisions, or other fields the agent should persist but not reveal literally to the user.
 - Do not log secret values.
 

package/docs/guides/channel-security.md

@@ -38,6 +38,8 @@ agentkit channels deliveries show <delivery-id>
 - Keep generic output webhook URLs on public HTTPS origins. AgentKit rejects localhost, private network, link-local, and metadata-service hosts before sending.
 - Do not route replies to a channel name from the inbound payload. `replyTo.channel` must be static config, and `recipientFrom` may only select the recipient identifier.
 - Do not remove `EVOLUTION_WEBHOOK_TOKEN` from Evolution WhatsApp webhooks. Evolution provider docs expose webhook delivery setup but no webhook signing-secret contract, so AgentKit requires a secret token query parameter and rejects requests without it.
+- Do not remove `UAZAPI_WEBHOOK_TOKEN` or `ZAPSTER_WEBHOOK_TOKEN`. These are AgentKit-owned URL secrets, not provider-issued tokens. The adapters require them because the providers' other webhook fields do not provide a strong shared-secret signature.
+- A local HTTPS tunnel may forward only authenticated `/channels/.../webhook` routes to `agentkit dev`; the local chat, inspect, tools, files, and conversation APIs remain loopback-only.
 - Keep `EVOLUTION_API_BASE_URL` on a public HTTPS origin. AgentKit rejects localhost, private network, link-local, and metadata-service hosts for Evolution outbound and media-download requests.
 - Inspect delivery IDs, hashes, redacted metadata, and statuses instead of raw provider payloads.
 - Keep channel plumbing out of the agent's application database. The user's Turso tables are for the agent's business data.

package/docs/guides/connect-whatsapp-uazapi.md

@@ -2,21 +2,17 @@
 
 ## Goal
 
-Connect a UAZAPI WhatsApp instance to a hosted AgentKit WhatsApp channel.
+Connect a UAZAPI WhatsApp instance to an AgentKit WhatsApp channel locally or when hosted.
 
 ## When To Use It
 
-Use this after `whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+Use this after `whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })` exists in `agentkit.config.ts`.
 
 ## Commands
 
 ```sh
-agentkit deploy
-agentkit channels connect whatsapp support-whatsapp --provider uazapi
-agentkit channels status support-whatsapp
-agentkit channels test support-whatsapp --message "hello"
-agentkit channels deliveries list support-whatsapp
-agentkit channels buffers list support-whatsapp
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | agentkit env set UAZAPI_WEBHOOK_TOKEN --stdin
+agentkit dev
 ```
 
 Required secrets:
@@ -24,11 +20,6 @@ Required secrets:
 ```txt
 UAZAPI_BASE_URL
 UAZAPI_TOKEN
-```
-
-Optional hardening secret:
-
-```txt
 UAZAPI_WEBHOOK_TOKEN
 ```
 
@@ -52,7 +43,28 @@ export default defineAgent({
 });
 ```
 
-## Setup Behavior
+## Local Usage
+
+`UAZAPI_WEBHOOK_TOKEN` is an AgentKit-owned secret, not a token issued by UAZAPI. Generate a different value for every channel and keep it in the ignored local `.env`:
+
+```sh
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | npm run agentkit -- env set UAZAPI_WEBHOOK_TOKEN --stdin
+npm run agentkit -- env set UAZAPI_BASE_URL --stdin
+npm run agentkit -- env set UAZAPI_TOKEN --stdin
+npm run agentkit -- dev
+```
+
+Expose the printed local port through an HTTPS tunnel, then register this exact URL with UAZAPI:
+
+```txt
+https://<tunnel-host>/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>
+```
+
+Configure UAZAPI with `addUrlEvents: false` and `addUrlTypesMessages: false` so it calls that exact URL. AgentKit allows a public tunnel host only on authenticated channel webhook paths; local chat, inspect, tools, files, and conversation APIs remain loopback-only.
+
+Send a real WhatsApp message after registration. A `200` response proves UAZAPI preserved the tokenized URL and AgentKit accepted it. A `channel_signature_invalid` response means the configured URL omitted, changed, or stripped the token. If the tunnel hostname changes, update the registered webhook URL.
+
+## Hosted Setup Behavior
 
 `agentkit channels connect whatsapp support-whatsapp --provider uazapi` creates or updates the hosted channel, verifies managed secrets, calls UAZAPI `/webhook`, confirms the configured webhook is listed by UAZAPI, then runs a synthetic inbound smoke.
 
@@ -62,7 +74,7 @@ Expected webhook URL shape:
 https://<deploy-host>/channels/support-whatsapp/whatsapp/uazapi/webhook
 ```
 
-If the channel declares `UAZAPI_WEBHOOK_TOKEN`, AgentKit registers the webhook URL with the token query parameter:
+AgentKit requires `UAZAPI_WEBHOOK_TOKEN` and registers the webhook URL with the token query parameter:
 
 ```txt
 https://<deploy-host>/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>
@@ -90,8 +102,9 @@ UAZAPI audio webhooks become normalized audio messages. The retryable channel wo
 
 - Keep phone numbers redacted in logs by default.
 - Do not store UAZAPI tokens in `agentkit.config.ts`.
-- Use optional `UAZAPI_WEBHOOK_TOKEN` when the endpoint should require a secret query token in addition to the public route.
-- UAZAPI does not expose a documented webhook body-signature contract in AgentKit V1; treat the optional query token as the hardening layer.
+- Keep `UAZAPI_WEBHOOK_TOKEN` configured. UAZAPI V1 has no body-signature contract, so AgentKit rejects webhooks without the secret query token.
+- UAZAPI does not expose a documented webhook body-signature contract in AgentKit V1; the AgentKit-owned query token is the authentication layer.
+- Treat the complete tokenized URL as a secret and rotate `UAZAPI_WEBHOOK_TOKEN` if it appears in logs or screenshots.
 - AgentKit ignores `fromMe` and `wasSentByApi` messages to avoid reply loops.
 - Text replies call UAZAPI `POST /send/text` with the `token` header and a body containing `number`, `text`, `readchat`, `async`, `track_source`, and `track_id`.
 - Real provider success is recorded as `provider_sent` only when UAZAPI returns a provider message id.
@@ -111,10 +124,10 @@ agentkit channels deliveries show <delivery-id>
 ## Troubleshooting
 
 `channel_secret_missing`:
-Set `UAZAPI_BASE_URL` and `UAZAPI_TOKEN` as hosted managed secrets. If the channel declares `UAZAPI_WEBHOOK_TOKEN`, set that managed secret too.
+Set `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, and `UAZAPI_WEBHOOK_TOKEN` as secrets.
 
 `channel_signature_invalid`:
-The optional UAZAPI webhook query token does not match.
+The required UAZAPI webhook query token does not match.
 
 `channel_provider_setup_invalid`:
 `UAZAPI_BASE_URL` is not an allowed HTTPS public base URL.

package/docs/guides/connect-whatsapp-zapster.md

@@ -2,21 +2,17 @@
 
 ## Goal
 
-Connect a Zapster WhatsApp account to a hosted AgentKit WhatsApp channel.
+Connect a Zapster WhatsApp account to an AgentKit WhatsApp channel locally or when hosted.
 
 ## When To Use It
 
-Use this after `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+Use this after `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })` exists in `agentkit.config.ts`.
 
 ## Commands
 
 ```sh
-agentkit deploy
-agentkit channels connect whatsapp support-whatsapp --provider zapster
-agentkit channels status support-whatsapp
-agentkit channels test support-whatsapp --message "hello"
-agentkit channels deliveries list support-whatsapp --since 24h
-agentkit channels buffers list support-whatsapp
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | agentkit env set ZAPSTER_WEBHOOK_TOKEN --stdin
+agentkit dev
 ```
 
 Required secrets:
@@ -25,11 +21,6 @@ Required secrets:
 ZAPSTER_API_KEY
 ZAPSTER_INSTANCE_ID
 ZAPSTER_WEBHOOK_ID
-```
-
-Optional hardening secret:
-
-```txt
 ZAPSTER_WEBHOOK_TOKEN
 ```
 
@@ -48,7 +39,8 @@ GROQ_API_KEY
 ## Files Created Or Edited
 
 - `agentkit.config.ts`: `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })`.
-- `.agentkit/deploy.json`: deploy state for resolving the hosted deploy.
+- `.env`: ignored local provider credentials and the AgentKit-owned webhook token.
+- `.agentkit/deploy.json`: deploy state only when using the hosted workflow.
 - No user-managed webhook server.
 
 ## Minimal Working Example
@@ -69,6 +61,28 @@ export default defineAgent({
 });
 ```
 
+## Local Usage
+
+`ZAPSTER_WEBHOOK_TOKEN` is an AgentKit-owned secret, not a token issued by Zapster. Generate a different value for every channel and keep it in the ignored local `.env`:
+
+```sh
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | npm run agentkit -- env set ZAPSTER_WEBHOOK_TOKEN --stdin
+npm run agentkit -- env set ZAPSTER_API_KEY --stdin
+npm run agentkit -- env set ZAPSTER_INSTANCE_ID --stdin
+npm run agentkit -- env set ZAPSTER_WEBHOOK_ID --stdin
+npm run agentkit -- dev
+```
+
+Expose the printed local port through an HTTPS tunnel, then register this exact URL with Zapster:
+
+```txt
+https://<tunnel-host>/channels/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>
+```
+
+Zapster stores a complete webhook URL and sends `X-Instance-ID` and `X-Webhook-ID` with deliveries. AgentKit requires both expected IDs and the URL secret because those identifiers alone are not cryptographic authentication. AgentKit allows a public tunnel host only on authenticated channel webhook paths; local chat, inspect, tools, files, and conversation APIs remain loopback-only.
+
+Send a real WhatsApp message after registration. A `200` response proves Zapster preserved the tokenized URL and AgentKit accepted it. A `channel_signature_invalid` response means the URL token or expected Zapster IDs did not match. If the tunnel hostname changes, update the registered webhook URL.
+
 To handle clients who send several WhatsApp messages before waiting, enable channel buffering:
 
 ```ts
@@ -123,7 +137,7 @@ export default defineAgent({
 
 Processing order:
 
-1. AgentKit validates Zapster origin headers and the optional webhook token.
+1. AgentKit validates Zapster origin headers and the required webhook token.
 2. Zapster audio payloads become normalized audio messages.
 3. AgentKit records `audio_received` and enqueues a channel job before acknowledging Zapster.
 4. The retryable channel worker downloads the media URL from a trusted Zapster HTTPS host using `ZAPSTER_API_KEY`.
@@ -132,7 +146,7 @@ Processing order:
 
 Zapster payloads must include a media download URL such as `audio.downloadUrl`, `audio.url`, `audio.mediaUrl`, or the snake_case equivalents. The URL must be HTTPS and hosted by Zapster; AgentKit rejects arbitrary webhook-provided hosts before sending `ZAPSTER_API_KEY`. If Zapster sends only a media ID without a download URL, AgentKit records `channel_audio_download_unavailable` and does not create an agent run for that audio in V1.
 
-## Setup Behavior
+## Hosted Setup Behavior
 
 `agentkit channels setup support-whatsapp` prints the stable AgentKit webhook URL. Paste it into Zapster webhook settings.
 
@@ -142,7 +156,7 @@ Expected webhook URL shape:
 https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook
 ```
 
-If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, register the Zapster URL with the token as a query parameter:
+AgentKit requires `ZAPSTER_WEBHOOK_TOKEN`; register the Zapster URL with the token as a query parameter:
 
 ```txt
 https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>
@@ -154,7 +168,8 @@ https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook?token=<
 - Do not store Zapster API keys in `agentkit.config.ts`.
 - Inbound validation uses Zapster's `X-Instance-ID`, `X-Webhook-ID`, `X-Message-ID`, `X-Attempt-Count`, and `User-Agent: Zapsterapi/...` headers.
 - Zapster webhook headers are origin validation, not a cryptographic body signature.
-- Use optional `ZAPSTER_WEBHOOK_TOKEN` in the webhook URL when the endpoint should require an extra secret known only to AgentKit and Zapster.
+- Keep `ZAPSTER_WEBHOOK_TOKEN` in the webhook URL. Zapster's metadata headers are not a shared-secret signature, so AgentKit rejects webhooks without the secret query token.
+- Treat the complete tokenized URL as a secret and rotate `ZAPSTER_WEBHOOK_TOKEN` if it appears in logs or screenshots.
 - Unsupported media should be logged as skipped/unsupported without creating an agent run.
 - AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`.
 - Outbound replies call `POST https://api.zapsterapi.com/v1/wa/messages` with bearer auth and a JSON body containing `recipient`, `text`, and `instance_id`.
@@ -177,10 +192,10 @@ agentkit channels buffers retry support-whatsapp <conversation-id>
 ## Troubleshooting
 
 `channel_secret_missing`:
-Set `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `ZAPSTER_WEBHOOK_ID` as hosted managed secrets. If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, set that managed secret too.
+Set `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, `ZAPSTER_WEBHOOK_ID`, and `ZAPSTER_WEBHOOK_TOKEN` as secrets.
 
 `channel_signature_invalid`:
-Zapster is not sending the expected instance/webhook IDs, or the optional query token does not match.
+Zapster is not sending the expected instance/webhook IDs, or the required query token does not match.
 
 `channel_unsupported_message_type` or skipped delivery:
 The inbound WhatsApp event was not supported text. Inspect the delivery record for provider metadata.

package/docs/guides/create-agent.md

@@ -39,6 +39,18 @@ cd support-demo
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 ```
 
+`agentkit new` can prompt for the project folder name when run in an interactive terminal:
+
+```sh
+npx @andreprado/agentkit@alpha new
+```
+
+Use `.` to create the capsule in the current directory:
+
+```sh
+npx @andreprado/agentkit@alpha new . --template blank
+```
+
 ## Windows PowerShell
 
 If PowerShell blocks `npm.ps1` or `npx.ps1` with `PSSecurityException`, run the same commands through the Windows command shims:

package/docs/guides/prepare-deploy.md

@@ -166,7 +166,7 @@ No .agentkit committed
 All required secret names are declared
 Prompt path exists
 Tools have input schemas
-Dangerous tools have permissions
+Read-only tools use `:read` permissions; dangerous tools use operator-only non-read permissions
 Managed Composio toolkit auth configs are available in AgentKit Cloud when configured
 Provider model is supported by AgentKit
 schema.sql is idempotent

package/docs/guides/security-rules.md

@@ -89,6 +89,7 @@ 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.
@@ -98,6 +99,8 @@ defineTool({
 - 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.

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/llms-full.txt

@@ -33,7 +33,8 @@ The capsule root is the runtime boundary. Run AgentKit commands from the directo
 Current commands:
 
 ```sh
-agentkit new <name> [--template blank|support|dentista] [--no-install]
+agentkit new [name] [--template blank|support|dentista] [--no-install]
+agentkit new .
 agentkit dev [--port <number>]
 agentkit open
 agentkit chat-ui --deploy
@@ -119,7 +120,7 @@ Use `agentkit feedback create` when AgentKit itself fails, confuses the coding a
 
 On Windows PowerShell, if `npm.ps1` or `npx.ps1` is blocked with `PSSecurityException`, run capsule scripts through the `.cmd` shims instead of changing the workflow. Examples: `npx.cmd @andreprado/agentkit@alpha new demo --template blank`, `npm.cmd run agentkit -- inspect`, `npm.cmd run agentkit -- knowledge sync`, and `npm.cmd run eval`.
 
-Managed Composio is configured with `composioManaged({...})` in `agentkit.config.ts` and is paid hosted AgentKit infrastructure. It requires a non-anonymous AgentKit Cloud deploy with `managed_composio`, uses one Composio settings profile per agent, injects `COMPOSIO_API_KEY` as an AgentKit-managed secret, resolves toolkit auth configs from AgentKit Cloud, validates toolkit readiness during `agentkit deploy doctor`, and exposes the generated `agentkit_composio_execute` tool only for explicit configured action slugs. Calendar starters should include `GOOGLECALENDAR_EVENTS_LIST`, `GOOGLECALENDAR_CREATE_EVENT`, and `GOOGLECALENDAR_UPDATE_EVENT`; create-event calls must pass UTC `start_datetime` plus explicit duration. Managed external write actions require tool input `confirmed: true` by default unless the integration sets `confirmExternalWrites: false`. See `docs/guides/add-managed-composio.md`.
+Managed Composio is configured with `composioManaged({...})` in `agentkit.config.ts` and is paid hosted AgentKit infrastructure. It requires a non-anonymous AgentKit Cloud deploy with `managed_composio`, uses one Composio settings profile per agent, injects `COMPOSIO_API_KEY` as an AgentKit-managed secret, resolves toolkit auth configs from AgentKit Cloud, validates toolkit readiness during `agentkit deploy doctor`, and exposes the generated `agentkit_composio_execute` tool only for explicit configured action slugs. Calendar starters should include `GOOGLECALENDAR_EVENTS_LIST`, `GOOGLECALENDAR_CREATE_EVENT`, and `GOOGLECALENDAR_UPDATE_EVENT`; create-event calls must pass UTC `start_datetime` plus explicit duration. An integration containing external write actions is operator-only; invoke it directly with `agentkit tool`, and pass `confirmed: true` for writes unless the integration disables that secondary check. See `docs/guides/add-managed-composio.md`.
 
 ## Create And Test A Capsule
 
@@ -139,6 +140,8 @@ npm run agentkit -- conversations list
 npm run agentkit -- inspect
 ```
 
+Run `agentkit new` without a name in an interactive terminal to be prompted for the project folder. Use `agentkit new .` to create the capsule in the current directory. Non-interactive scripts should pass a name or `.` explicitly.
+
 Expected first chat output:
 
 ```txt
@@ -402,6 +405,7 @@ Rules:
 - `runtime: "edge"` is required when `channels` are configured.
 - Channel names are stable lowercase identifiers and must be unique.
 - Config stores secret names only, never secret values.
+- UAZAPI and Zapster WhatsApp channels require `UAZAPI_WEBHOOK_TOKEN` and `ZAPSTER_WEBHOOK_TOKEN`; webhooks without the matching query token are rejected.
 - AgentKit owns channel webhook URLs, dedupe, identities, queue state, and delivery logs.
 - Do not store channel plumbing in the user's Turso database.
 - Use `buffer.mode: "debounce"` when a channel should coalesce rapid client messages into one agent run.
@@ -450,6 +454,7 @@ Zapster WhatsApp required secrets:
 ZAPSTER_API_KEY
 ZAPSTER_INSTANCE_ID
 ZAPSTER_WEBHOOK_ID
+ZAPSTER_WEBHOOK_TOKEN
 ```
 
 UAZAPI WhatsApp required secrets:
@@ -457,8 +462,11 @@ UAZAPI WhatsApp required secrets:
 ```txt
 UAZAPI_BASE_URL
 UAZAPI_TOKEN
+UAZAPI_WEBHOOK_TOKEN
 ```
 
+`UAZAPI_WEBHOOK_TOKEN` and `ZAPSTER_WEBHOOK_TOKEN` are AgentKit-owned secrets generated by the user, not provider-issued credentials. For local `agentkit dev`, expose the printed port through an HTTPS tunnel and register the exact `/channels/<name>/whatsapp/<provider>/webhook?token=<secret>` URL. Only authenticated channel webhook routes accept a tunnel host; other local endpoints remain loopback-only.
+
 Evolution API WhatsApp required secrets:
 
 ```txt
@@ -569,7 +577,7 @@ agentkit channels deliveries list support-telegram
 agentkit channels deliveries show <delivery-id>
 ```
 
-`channels connect` creates or refreshes the channel resource, validates secrets, runs provider setup when supported, then runs the official synthetic smoke. `channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`. `channels setup <uazapi-whatsapp-name> --apply` calls UAZAPI `/webhook` and requires `UAZAPI_BASE_URL` plus `UAZAPI_TOKEN`. `channels setup <evolution-whatsapp-name> --apply` calls Evolution API `/webhook/set/{instance}` and requires `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `EVOLUTION_WEBHOOK_TOKEN`.
+`channels connect` creates or refreshes the channel resource, validates secrets, runs provider setup when supported, then runs the official synthetic smoke. `channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`. `channels setup <uazapi-whatsapp-name> --apply` calls UAZAPI `/webhook` and requires `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, and `UAZAPI_WEBHOOK_TOKEN`. `channels setup <evolution-whatsapp-name> --apply` calls Evolution API `/webhook/set/{instance}` and requires `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `EVOLUTION_WEBHOOK_TOKEN`.
 
 Discord slash-command mode validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against `DISCORD_PUBLIC_KEY`, answers signed `PING` requests with `type: 1`, acknowledges slash commands with a deferred response, then sends the final answer as an interaction follow-up. Discord bot mode uses `DISCORD_BOT_TOKEN`, Discord Gateway `MESSAGE_CREATE`, Message Content Intent, and `/channels/<channel_id>/messages` bot replies. Discord channels support buffering but do not support `audio` in V1.
 
@@ -583,8 +591,8 @@ AGENTKIT_RUN_EVOLUTION_CHANNEL_TESTS=1 bun test
 ```
 
 Telegram smoke also requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
-Zapster smoke also requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
-UAZAPI smoke also requires `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, and `AGENTKIT_UAZAPI_TO`.
+Zapster smoke also requires `ZAPSTER_API_KEY`, `ZAPSTER_WEBHOOK_TOKEN`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+UAZAPI smoke also requires `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, `UAZAPI_WEBHOOK_TOKEN`, and `AGENTKIT_UAZAPI_TO`.
 Evolution smoke also requires `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `AGENTKIT_EVOLUTION_TO`.
 
 ## Tool Contract
@@ -646,6 +654,7 @@ Tool runtime rules:
 - `timeoutMs` overrides the default;
 - tool calls are saved in AgentKit-managed local storage;
 - secret values are redacted before storage.
+- permissions ending in `:read` may run automatically; any other declared permission requires a reviewed direct `agentkit tool` invocation and is blocked from chat, channels, and evals;
 - tools that need SQL use canonical `ctx.db`; `ctx.database` and `ctx.storage.sql` are supported aliases;
 - tools can use `ctx.db.batch([...])` for atomic writes; local tools can also use `ctx.db.transaction(async (tx) => ...)`;
 - tools can inspect `ctx.runtime` with `{ environment, invocation, target, database }`;
@@ -849,6 +858,8 @@ POST /v1/chat
 GET  /v1/conversations
 GET  /v1/conversations/:id
 GET  /v1/conversations/:id/trace
+POST /channels/<name>/<type>/<provider>/webhook
+POST /channels/<name>/webhook
 ```
 
 Chat request:
@@ -1000,6 +1011,7 @@ docs/
 Local `.env` is development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted deploys require an AgentKit Cloud account with `cloudflare_deploy_alpha` or purchased/manual deploy slots. First-time paid access uses `agentkit billing checkout --slots <count>` and `agentkit billing claim billint_... --secret bsec_...`; existing accounts use `agentkit login --token ...`. Hosted secrets use `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.
+Agent Capsules are trusted executable TypeScript, not sandboxed configuration. Run AgentKit commands only in Capsules whose config, tools, evals, and sync modules you trust.
 
 ## Hosted Deploy Contract
 

package/docs/llms.txt

@@ -8,6 +8,7 @@ Task guides:
 
 - Create a capsule: `docs/guides/create-agent.md`
 - Add a TypeScript tool: `docs/guides/add-tool.md`
+- Use TypeSafe/Jev inside a capsule tool: `docs/guides/use-jev.md`
 - Add Knowledge from local docs/CSVs: `docs/guides/add-knowledge.md`
 - Run or prepare evals: `docs/guides/run-evals.md`
 - Improve from production traces: `docs/guides/improve-from-production.md`
@@ -35,8 +36,9 @@ Task guides:
 Current local commands:
 
 ```sh
-agentkit new <name> --template blank|support|dentista
-agentkit new <name> --template blank --no-install
+agentkit new [name] --template blank|support|dentista
+agentkit new . --template blank
+agentkit new [name] --template blank --no-install
 agentkit docs full
 agentkit env set <NAME> --stdin
 agentkit env list
@@ -119,6 +121,10 @@ POST /v1/chat
 GET  /v1/conversations
 GET  /v1/conversations/:id
 GET  /v1/conversations/:id/trace
+POST /channels/<name>/<type>/<provider>/webhook
+POST /channels/<name>/webhook
 ```
 
+Only authenticated channel webhook routes may arrive through a public HTTPS tunnel. Other local endpoints remain loopback-only. UAZAPI and Zapster use user-generated AgentKit URL secrets in `?token=...`; the providers do not issue those values.
+
 Local `.env` is for development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted deploys require an AgentKit Cloud account with `cloudflare_deploy_alpha` or purchased/manual deploy slots. Use `agentkit billing checkout` + `agentkit billing claim` for first-time paid access, or `agentkit login --token ...` when the user already has an `agk_user_...` token. Production uses managed secrets in the hosted contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.26",
   "private": false,
   "type": "module",
   "repository": {
@@ -31,10 +31,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.75.5",
-    "@earendil-works/pi-coding-agent": "^0.75.5",
     "@libsql/client": "^0.15.15",
-    "esbuild": "^0.28.0",
-    "tsx": "^4.22.3",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.23.12",
     "typebox": "^1.1.38"
   },
   "devDependencies": {

package/src/cli/commands/channels.ts

@@ -1221,7 +1221,7 @@ function defaultChannelSecretsForCli(type: string, provider: string, mode?: "int
   }
 
   if (type === "whatsapp" && provider === "zapster") {
-    return ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"];
+    return ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID", "ZAPSTER_WEBHOOK_TOKEN"];
   }
 
   if (type === "whatsapp" && provider === "meta") {
@@ -1229,7 +1229,7 @@ function defaultChannelSecretsForCli(type: string, provider: string, mode?: "int
   }
 
   if (type === "whatsapp" && provider === "uazapi") {
-    return ["UAZAPI_BASE_URL", "UAZAPI_TOKEN"];
+    return ["UAZAPI_BASE_URL", "UAZAPI_TOKEN", "UAZAPI_WEBHOOK_TOKEN"];
   }
 
   if (type === "whatsapp" && provider === "evolution") {

package/src/cli/help.ts

@@ -13,7 +13,7 @@ Usage:
   agentkit <command> [options]
 
 Start:
-  agentkit new <name> [--template blank|support|dentista] [--no-install]
+  agentkit new [name] [--template blank|support|dentista] [--no-install]
   agentkit dev
   agentkit open
   agentkit chat-ui --deploy
@@ -59,7 +59,7 @@ export function renderCommandReference(): string {
   return `AgentKit Command Reference
 
 Usage:
-  agentkit new <name> [--template blank|support|dentista] [--no-install]
+  agentkit new [name] [--template blank|support|dentista] [--no-install]
   agentkit dev [--port <number>]
   agentkit open
   agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
@@ -189,13 +189,15 @@ Examples:
   agentkit tool lookup_order --input '{"orderId":"A100"}'
   agentkit eval run
 
+  agentkit new
+  agentkit new .
   agentkit new clara-dentista --template dentista
 `;
 }
 
 export function renderCommandHelp(command: string): string {
   const usage: Record<string, string> = {
-    new: "agentkit new <name> [--template blank|support|dentista] [--no-install]",
+    new: "agentkit new [name] [--template blank|support|dentista] [--no-install]",
     dev: "agentkit dev [--port <number>]",
     open: "agentkit open",
     "chat-ui": "agentkit chat-ui --deploy [--port <number>] [--token-file <path>]",

package/src/cli/index.ts

@@ -31,6 +31,7 @@ import { inspectAgentCapsule } from "../runtime/inspect";
 import { AgentKitError, isAgentKitError } from "../runtime/errors";
 import { prepareVpsDeploy } from "../runtime/targets/vps/deploy";
 import { parseArgs, isHelpRequested, type ParsedArgs } from "./args";
+import { resolveNewProjectName } from "./new-command";
 import {
   defaultAgentKitDevPort,
   defaultDeployChatAccessTokenName,
@@ -114,14 +115,10 @@ async function main() {
   warnIfUnsupportedNode();
 
   if (args.command === "new") {
-    const [name] = args.positional;
+    const name = await resolveNewProjectName(args.positional);
     const template = String(args.flags.template ?? "blank");
     const shouldInstall = args.flags["no-install"] !== true;
 
-    if (!name) {
-      throw new Error("Missing project name. Usage: agentkit new <name> [--template blank|support|dentista] [--no-install]");
-    }
-
     const result = await createProject({ name, template, cwd: process.cwd() });
     console.log(`Created ${result.name} at ${result.path}`);