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

package/src/cli/new-command.ts

@@ -0,0 +1,41 @@
+import { createInterface } from "node:readline/promises";
+
+const newUsage = "agentkit new [name] [--template blank|support|dentista] [--no-install]";
+
+export async function resolveNewProjectName(
+  positional: string[],
+  promptProjectName: () => Promise<string> = promptForProjectName,
+): Promise<string> {
+  const [name] = positional;
+
+  if (name) {
+    return name;
+  }
+
+  const promptedName = (await promptProjectName()).trim();
+
+  if (!promptedName) {
+    throw new Error(`Project name is required. Usage: ${newUsage}`);
+  }
+
+  return promptedName;
+}
+
+async function promptForProjectName(): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      `Missing project name. Usage: ${newUsage}. Run \`agentkit new\` in an interactive terminal to be prompted, or pass \`agentkit new <name>\` / \`agentkit new .\` in scripts.`,
+    );
+  }
+
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    return await readline.question("Project folder name (or . for current directory): ");
+  } finally {
+    readline.close();
+  }
+}

package/src/index.ts

@@ -627,11 +627,11 @@ function defaultDiscordChannelSecrets(mode: DiscordChannelMode): string[] {
 
 function defaultWhatsappChannelSecrets(provider: WhatsappChannelProvider): string[] {
   if (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 (provider === "uazapi") {
-    return ["UAZAPI_BASE_URL", "UAZAPI_TOKEN"];
+    return ["UAZAPI_BASE_URL", "UAZAPI_TOKEN", "UAZAPI_WEBHOOK_TOKEN"];
   }
 
   if (provider === "evolution") {

package/src/runtime/channels/whatsapp-uazapi.ts

@@ -55,12 +55,12 @@ const UAZAPI_IGNORED_EVENTS = new Set(["connection", "presence", "history"]);
 export const uazapiWhatsappChannelAdapter: ChannelAdapter = {
   type: "whatsapp",
   provider: "uazapi",
-  requiredSecrets: ["UAZAPI_BASE_URL", "UAZAPI_TOKEN"],
+  requiredSecrets: ["UAZAPI_BASE_URL", "UAZAPI_TOKEN", "UAZAPI_WEBHOOK_TOKEN"],
   verifyWebhook(input) {
-    const optionalTokenResult = verifyOptionalWebhookToken(input);
+    const tokenResult = verifyWebhookToken(input);
 
-    if (!optionalTokenResult.ok) {
-      return optionalTokenResult;
+    if (!tokenResult.ok) {
+      return tokenResult;
     }
 
     try {
@@ -513,7 +513,9 @@ export async function getUazapiStatus(
   input: ChannelStatusInput,
   fetcher: UazapiFetch = fetch,
 ): Promise<ChannelStatusResult> {
-  const missingSecrets = ["UAZAPI_BASE_URL", "UAZAPI_TOKEN"].filter((secret) => !input.secrets[secret]);
+  const missingSecrets = ["UAZAPI_BASE_URL", "UAZAPI_TOKEN", "UAZAPI_WEBHOOK_TOKEN"].filter(
+    (secret) => !input.secrets[secret],
+  );
 
   if (missingSecrets.length > 0) {
     return {
@@ -617,13 +619,7 @@ export function uazapiApiUrl(baseUrl: string, path: string): string {
   return new URL(normalizedPath, `${base}/`).href;
 }
 
-function verifyOptionalWebhookToken(input: WebhookVerificationInput): WebhookVerificationResult {
-  const expectsToken = input.channel.secrets.includes("UAZAPI_WEBHOOK_TOKEN");
-
-  if (!expectsToken) {
-    return { ok: true };
-  }
-
+function verifyWebhookToken(input: WebhookVerificationInput): WebhookVerificationResult {
   const expectedToken = input.secrets.UAZAPI_WEBHOOK_TOKEN;
 
   if (!expectedToken) {

package/src/runtime/channels/whatsapp-zapster.ts

@@ -13,7 +13,7 @@ import { AgentKitError } from "../errors";
 export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
   type: "whatsapp",
   provider: "zapster",
-  requiredSecrets: ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"],
+  requiredSecrets: ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID", "ZAPSTER_WEBHOOK_TOKEN"],
   verifyWebhook(input) {
     const expectedInstanceId = input.secrets.ZAPSTER_INSTANCE_ID;
     const expectedWebhookId = input.secrets.ZAPSTER_WEBHOOK_ID;
@@ -34,10 +34,10 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
       };
     }
 
-    const optionalTokenResult = verifyOptionalWebhookToken(input);
+    const tokenResult = verifyWebhookToken(input);
 
-    if (!optionalTokenResult.ok) {
-      return optionalTokenResult;
+    if (!tokenResult.ok) {
+      return tokenResult;
     }
 
     const instanceId = input.headers.get("x-instance-id");
@@ -165,9 +165,12 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
     return sendZapsterMessage(input);
   },
   getStatus(input) {
-    const missingSecrets = ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"].filter(
-      (secret) => !input.secrets[secret],
-    );
+    const missingSecrets = [
+      "ZAPSTER_API_KEY",
+      "ZAPSTER_INSTANCE_ID",
+      "ZAPSTER_WEBHOOK_ID",
+      "ZAPSTER_WEBHOOK_TOKEN",
+    ].filter((secret) => !input.secrets[secret]);
 
     if (missingSecrets.length > 0) {
       return {
@@ -260,13 +263,7 @@ function normalizeZapsterAudio(value: Record<string, unknown>): NormalizedZapste
   };
 }
 
-function verifyOptionalWebhookToken(input: WebhookVerificationInput): WebhookVerificationResult {
-  const expectsToken = input.channel.secrets.includes("ZAPSTER_WEBHOOK_TOKEN");
-
-  if (!expectsToken) {
-    return { ok: true };
-  }
-
+function verifyWebhookToken(input: WebhookVerificationInput): WebhookVerificationResult {
   const expectedToken = input.secrets.ZAPSTER_WEBHOOK_TOKEN;
 
   if (!expectedToken) {

package/src/runtime/config.ts

@@ -718,7 +718,7 @@ function validateWhatsappChannel(value: Record<string, unknown>, index: number):
   if (value.provider === "zapster") {
     expectRequiredSecrets(
       value.secrets,
-      ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"],
+      ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID", "ZAPSTER_WEBHOOK_TOKEN"],
       `channels[${index}]`,
     );
     return;
@@ -736,7 +736,7 @@ function validateWhatsappChannel(value: Record<string, unknown>, index: number):
   if (value.provider === "uazapi") {
     expectRequiredSecrets(
       value.secrets,
-      ["UAZAPI_BASE_URL", "UAZAPI_TOKEN"],
+      ["UAZAPI_BASE_URL", "UAZAPI_TOKEN", "UAZAPI_WEBHOOK_TOKEN"],
       `channels[${index}]`,
     );
     return;

package/src/runtime/dev-server.ts

@@ -55,6 +55,8 @@ export type AgentDevServer = {
 
 const DEFAULT_PORT = 4123;
 const DEFAULT_HOSTNAME = "localhost";
+const MAX_JSON_BODY_BYTES = 1_048_576;
+const MAX_WEBHOOK_BODY_BYTES = 1_048_576;
 const CHANNEL_DEDUPE_TTL_MS = 6 * 60 * 60 * 1000;
 const CHANNEL_DEDUPE_MAX_KEYS = 10_000;
 
@@ -179,8 +181,8 @@ async function handleNodeRequest(
   options: DevHttpServerOptions,
 ): Promise<void> {
   try {
+    const request = nodeRequestToFetchRequest(incoming, options);
     const capsule = await loadAgentCapsule(capsuleRoot);
-    const request = nodeRequestToFetchRequest(incoming);
     const response = await handleDevServerRequest(capsule, request, channelRuntime, options);
     await writeFetchResponse(outgoing, response);
   } catch (error) {
@@ -188,7 +190,7 @@ async function handleNodeRequest(
   }
 }
 
-function nodeRequestToFetchRequest(incoming: IncomingMessage): Request {
+function nodeRequestToFetchRequest(incoming: IncomingMessage, options: DevHttpServerOptions): Request {
   const headers = new Headers();
 
   for (const [key, value] of Object.entries(incoming.headers)) {
@@ -201,9 +203,24 @@ function nodeRequestToFetchRequest(incoming: IncomingMessage): Request {
     }
   }
 
-  const protocol = headers.get("x-forwarded-proto") ?? "http";
   const host = headers.get("host") ?? `${DEFAULT_HOSTNAME}:${DEFAULT_PORT}`;
-  const url = new URL(incoming.url ?? "/", `${protocol}://${host}`).href;
+  const hostname = requestHeaderHostname(`http://${host}`, "Host");
+  const pathname = normalizePath(new URL(incoming.url ?? "/", "http://localhost").pathname);
+
+  if (options.access === "local" && !isChannelWebhookPath(pathname)) {
+    assertLoopbackHostname(hostname, "Host");
+
+    const origin = headers.get("origin");
+    if (origin) {
+      assertLoopbackHostname(requestHeaderHostname(origin, "Origin"), "Origin");
+    }
+
+    if (headers.get("sec-fetch-site") === "cross-site") {
+      throw new AgentKitError("request_origin_invalid", "Cross-site browser requests are not allowed by the local dev server.");
+    }
+  }
+
+  const url = new URL(incoming.url ?? "/", `http://${host}`).href;
   const init: RequestInit & { duplex?: "half" } = {
     method: incoming.method ?? "GET",
     headers,
@@ -217,6 +234,28 @@ function nodeRequestToFetchRequest(incoming: IncomingMessage): Request {
   return new Request(url, init);
 }
 
+function isChannelWebhookPath(pathname: string): boolean {
+  return /^\/channels\/[^/]+\/(?:(?:website|telegram|whatsapp|discord|slack|webhook)\/[^/]+\/)?webhook$/.test(
+    pathname,
+  );
+}
+
+function requestHeaderHostname(value: string, header: string): string {
+  try {
+    return new URL(value).hostname;
+  } catch {
+    throw new AgentKitError("request_origin_invalid", `${header} is not a valid URL authority.`);
+  }
+}
+
+function assertLoopbackHostname(hostname: string, header: string): void {
+  if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]") {
+    return;
+  }
+
+  throw new AgentKitError("request_origin_invalid", `${header} must target localhost while dev access is local.`);
+}
+
 async function writeFetchResponse(outgoing: ServerResponse, response: Response): Promise<void> {
   outgoing.statusCode = response.status;
   response.headers.forEach((value, key) => {
@@ -489,7 +528,7 @@ async function handlePortableChannel(
   }
 
   const adapter = adapterForChannel(route.type, route.provider);
-  const rawBody = request.method === "GET" ? "" : await request.text();
+  const rawBody = request.method === "GET" ? "" : await readRequestTextWithLimit(request, MAX_WEBHOOK_BODY_BYTES);
   const rawEvent: RawWebhookEvent = {
     type: route.type,
     provider: route.provider,
@@ -958,14 +997,19 @@ export class BoundedDedupeCache {
   }
 }
 
-async function readRequestBytesWithLimit(request: Request, maxBytes: number): Promise<Uint8Array> {
+async function readRequestBytesWithLimit(
+  request: Request,
+  maxBytes: number,
+  errorCode = "file_too_large",
+  label = "File",
+): Promise<Uint8Array> {
   const contentLength = request.headers.get("content-length");
 
   if (contentLength) {
     const declaredBytes = Number(contentLength);
 
     if (Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
-      throw new AgentKitError("file_too_large", `File exceeds max upload size of ${maxBytes} bytes.`);
+      throw new AgentKitError(errorCode, `${label} exceeds the maximum size of ${maxBytes} bytes.`);
     }
   }
 
@@ -988,7 +1032,7 @@ async function readRequestBytesWithLimit(request: Request, maxBytes: number): Pr
 
     if (total > maxBytes) {
       await reader.cancel().catch(() => undefined);
-      throw new AgentKitError("file_too_large", `File exceeds max upload size of ${maxBytes} bytes.`);
+      throw new AgentKitError(errorCode, `${label} exceeds the maximum size of ${maxBytes} bytes.`);
     }
 
     chunks.push(value);
@@ -1005,6 +1049,11 @@ async function readRequestBytesWithLimit(request: Request, maxBytes: number): Pr
   return bytes;
 }
 
+async function readRequestTextWithLimit(request: Request, maxBytes: number): Promise<string> {
+  const bytes = await readRequestBytesWithLimit(request, maxBytes, "request_too_large", "Request body");
+  return new TextDecoder().decode(bytes);
+}
+
 async function listConversations(capsule: LoadedAgentCapsule) {
   const store = await openCapsuleStore(capsule);
 
@@ -1069,8 +1118,12 @@ async function readJsonBody(request: Request): Promise<unknown> {
   }
 
   try {
-    return await request.json();
+    return JSON.parse(await readRequestTextWithLimit(request, MAX_JSON_BODY_BYTES));
   } catch (error) {
+    if (isAgentKitError(error)) {
+      throw error;
+    }
+
     throw new AgentKitError("validation_error", "Request body must be valid JSON.", { cause: error });
   }
 }
@@ -1158,11 +1211,22 @@ function statusForError(error: unknown): number {
     return 409;
   }
 
+  if (error.code === "request_origin_invalid" || error.code === "tool_authorization_required") {
+    return 403;
+  }
+
+  if (error.code === "request_too_large") {
+    return 413;
+  }
+
+  if (error.code === "channel_signature_invalid") {
+    return 401;
+  }
+
   if (
     error.code === "file_key_invalid" ||
     error.code === "file_too_large" ||
     error.code === "channel_payload_invalid" ||
-    error.code === "channel_signature_invalid" ||
     error.code === "channel_secret_missing"
   ) {
     return 400;

package/src/runtime/integrations/composio.ts

@@ -91,7 +91,9 @@ export function createManagedComposioTools(
       ].join("\n\n"),
       visibility: "user",
       secrets: [MANAGED_COMPOSIO_API_KEY_SECRET],
-      permissions: integration.allowedTools.map((toolName) => `composio:${toolName.toLowerCase()}`),
+      permissions: integration.allowedTools.map(
+        (toolName) => `composio:${toolName.toLowerCase()}:${isComposioWriteAction(toolName) ? "write" : "read"}`,
+      ),
       timeoutMs: 60_000,
       inputSchema: {
         type: "object",

package/src/runtime/targets/cloudflare/build.ts

@@ -497,11 +497,11 @@ export function webhookOutputChannel(input) {
 
 function defaultWhatsappChannelSecrets(provider) {
   if (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 (provider === "uazapi") {
-    return ["UAZAPI_BASE_URL", "UAZAPI_TOKEN"];
+    return ["UAZAPI_BASE_URL", "UAZAPI_TOKEN", "UAZAPI_WEBHOOK_TOKEN"];
   }
 
   if (provider === "evolution") {
@@ -2124,6 +2124,7 @@ async function executeHostedTool(request) {
 
   const input = normalizeOptionalNulls(request.input ?? {}, tool.inputSchema);
   validateSchema(input, tool.inputSchema, \`tool "\${tool.name}" input\`);
+  assertToolInvocationAuthorized(tool, request.invocation ?? "tool");
 
   const secrets = resolveToolSecrets(tool, request.env);
   const database = createHostedDatabaseRunner(request.env);
@@ -2167,6 +2168,23 @@ async function executeHostedTool(request) {
   };
 }
 
+function assertToolInvocationAuthorized(tool, invocation) {
+  if (invocation === "tool") {
+    return;
+  }
+
+  const privilegedPermissions = (tool.permissions ?? []).filter((permission) => !permission.endsWith(":read"));
+
+  if (privilegedPermissions.length === 0) {
+    return;
+  }
+
+  throw agentKitError(
+    "tool_authorization_required",
+    \`Tool "\${tool.name}" requires an explicit operator invocation because it declares privileged permissions: \${privilegedPermissions.join(", ")}.\`,
+  );
+}
+
 function failedHostedToolCall(tools, request, error) {
   const tool = tools.find((candidate) => candidate.name === request.name);
 

package/src/runtime/tools.ts

@@ -81,6 +81,7 @@ async function executeToolCall(
 
     input = normalizeOptionalNulls(input, tool.inputSchema);
     validateSchema(input, tool.inputSchema, `tool "${tool.name}" input`);
+    assertToolInvocationAuthorized(tool, options.runtime);
 
     const { secrets, secretValues } = resolveToolSecrets(tool, options.env ?? process.env);
     const database = createLocalDatabaseRunner(options.store);
@@ -133,6 +134,23 @@ async function executeToolCall(
   }
 }
 
+function assertToolInvocationAuthorized(tool: AgentTool, runtime: ToolRuntimeContext): void {
+  if (runtime.invocation === "tool") {
+    return;
+  }
+
+  const privilegedPermissions = (tool.permissions ?? []).filter((permission) => !permission.endsWith(":read"));
+
+  if (privilegedPermissions.length === 0) {
+    return;
+  }
+
+  throw new AgentKitError(
+    "tool_authorization_required",
+    `Tool "${tool.name}" requires an explicit operator invocation because it declares privileged permissions: ${privilegedPermissions.join(", ")}. Run it with "agentkit tool ${tool.name} --input '<json>'" after reviewing the exact action.`,
+  );
+}
+
 function renderToolOutput(
   tool: AgentTool,
   input: unknown,

package/src/templates/skills/agentkit-build-agent/SKILL.md

@@ -7,7 +7,7 @@ description: Use when the owner gives a natural-language brief for a new or chan
 
 Use this when the owner asks for an agent in plain language.
 
-The owner should only need to run `agentkit new <name>`, open the capsule in Codex or another coding agent, and say what agent they want. Do not send them back to the CLI for a brief wizard. Treat their chat message as the brief and build the first useful local capsule.
+The owner should only need to run `agentkit new [name]` or `agentkit new .`, open the capsule in Codex or another coding agent, and say what agent they want. Do not send them back to the CLI for a brief wizard. Treat their chat message as the brief and build the first useful local capsule.
 
 ## Workflow
 
@@ -16,7 +16,7 @@ The owner should only need to run `agentkit new <name>`, open the capsule in Cod
 3. Infer the first useful local version from the owner's brief and the spec. Do not ask the owner to fill a form.
 4. Edit `prompts/instructions.md` for behavior, boundaries, intake questions, escalation rules, and tool-use policy.
 5. For scheduling, deadlines, reminders, or any relative-date behavior, set `timeZone` in `agentkit.config.ts` to the business/user timezone. AgentKit injects the current date, weekday, timestamp, and timezone dynamically at runtime; do not hardcode today's date in prompts.
-6. Add tools only when the agent needs action, live data, authorization-sensitive data, or durable writes.
+6. Add tools when the agent needs action, live data, authorization-sensitive data, durable writes, or a requested external judgment such as TypeSafe/Jev. Use `skills/agentkit-tools/SKILL.md` for the tool workflow and Jev guidance.
 7. Add database tables to `schema.sql` or ordered `migrations/*.sql` when the agent owns records.
 8. Add `sync.ts` and `seed.sql` with `npm run agentkit -- sync init` when the agent depends on external catalogs or recurring imports.
 9. Turn requirements into checks as you build. Every privacy rule, external write, confirmation step, business-hour rule, timezone rule, required intake field, and customer-data boundary needs an eval, direct tool check, fixture, or deterministic fake path.

package/src/templates/skills/agentkit-capsule/SKILL.md

@@ -9,7 +9,7 @@ Use this first inside an AgentKit Agent Capsule.
 
 ## Owner-To-Codex Contract
 
-The owner has already done the setup work by running `agentkit new <name>` and opening this folder in a coding agent. When they ask for an agent in natural language, that message is the brief.
+The owner has already done the setup work by running `agentkit new [name]` or `agentkit new .` and opening this folder in a coding agent. When they ask for an agent in natural language, that message is the brief.
 
 - Do not ask the owner to run a wizard, fill a form, or prepare `AGENT_SPEC.md`.
 - Route immediately to `skills/agentkit-build-agent/SKILL.md`.
@@ -39,7 +39,7 @@ If a real conversation reveals a bug or risky behavior, convert it into a regres
 
 - Build or reshape the agent from the owner's brief: `skills/agentkit-build-agent/SKILL.md`
 - Edit prompts: `skills/agentkit-prompts/SKILL.md`
-- Add actions or external data: `skills/agentkit-tools/SKILL.md`
+- Add actions, external data, or TypeSafe/Jev judgments: `skills/agentkit-tools/SKILL.md`
 - Add AgentKit-managed integrations such as managed Composio: `skills/agentkit-integrations/SKILL.md`
 - Add database tables or database-backed tools: `skills/agentkit-database/SKILL.md`
 - Add docs, FAQs, prices, policies, or CSV facts: `skills/agentkit-knowledge/SKILL.md`

package/src/templates/skills/agentkit-channels/references/whatsapp-uazapi.md

@@ -5,11 +5,6 @@ Required secrets:
 ```txt
 UAZAPI_BASE_URL
 UAZAPI_TOKEN
-```
-
-Optional hardening secret:
-
-```txt
 UAZAPI_WEBHOOK_TOKEN
 ```
 
@@ -18,15 +13,13 @@ Audio transcription also needs the configured transcription secret, usually `OPE
 Commands:
 
 ```sh
-agentkit deploy
-agentkit channels add whatsapp support-whatsapp --provider uazapi
-agentkit channels setup support-whatsapp --apply
-agentkit channels status support-whatsapp
-agentkit channels test support-whatsapp --message "hello"
-agentkit channels deliveries list support-whatsapp
+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
 ```
 
-AgentKit applies UAZAPI setup by calling `/webhook` with the stable hosted URL and then confirming that UAZAPI lists the configured webhook. If the channel declares `UAZAPI_WEBHOOK_TOKEN`, AgentKit appends `?token=<UAZAPI_WEBHOOK_TOKEN>` to the registered webhook URL.
+`UAZAPI_WEBHOOK_TOKEN` is generated by the user for AgentKit; UAZAPI does not issue it. Expose the local port through an HTTPS tunnel and register the exact `/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>` URL with `addUrlEvents: false` and `addUrlTypesMessages: false`. Send a real message to confirm UAZAPI preserves the complete URL.
 
 Inbound UAZAPI `messages` webhooks normalize text and audio messages. `fromMe` and `wasSentByApi` messages are skipped to avoid reply loops. Unsupported media should be logged as skipped/unsupported without creating an agent run.
 

package/src/templates/skills/agentkit-channels/references/whatsapp-zapster.md

@@ -6,11 +6,6 @@ Required secrets:
 ZAPSTER_API_KEY
 ZAPSTER_INSTANCE_ID
 ZAPSTER_WEBHOOK_ID
-```
-
-Optional hardening secret:
-
-```txt
 ZAPSTER_WEBHOOK_TOKEN
 ```
 
@@ -19,15 +14,14 @@ Audio transcription also needs the configured transcription secret, usually `OPE
 Commands:
 
 ```sh
-agentkit deploy
-agentkit channels add whatsapp support-whatsapp --provider zapster
-agentkit channels setup support-whatsapp
-agentkit channels status support-whatsapp
-agentkit channels test support-whatsapp --message "hello"
-agentkit channels deliveries list support-whatsapp
+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
 ```
 
-Paste the stable AgentKit webhook URL into Zapster settings. If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, append `?token=<ZAPSTER_WEBHOOK_TOKEN>` to the Zapster webhook URL. Keep phone numbers redacted in logs by default.
+`ZAPSTER_WEBHOOK_TOKEN` is generated by the user for AgentKit; Zapster does not issue it. Expose the local port through an HTTPS tunnel and register the exact `/channels/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>` URL. Send a real message to confirm Zapster preserves the complete URL. Keep phone numbers redacted in logs by default.
 
 AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`. Unsupported media should be logged as skipped/unsupported without creating an agent run.
 

package/src/templates/skills/agentkit-integrations/SKILL.md

@@ -42,7 +42,7 @@ Keep the action list explicit. Do not expose the whole Composio catalog by defau
 
 For Google Calendar, do not configure create-only access. Include `GOOGLECALENDAR_EVENTS_LIST` so the agent can inspect availability before writing. For `GOOGLECALENDAR_CREATE_EVENT`, pass UTC `start_datetime` and explicit `event_duration_minutes` or `event_duration_hour`; AgentKit blocks Composio's implicit 30-minute duration default.
 
-Managed Composio write actions require tool input `confirmed: true` by default. Set it only after the owner/user confirms the exact external change. Use `confirmExternalWrites: false` only when the capsule implements an equivalent confirmation guard elsewhere.
+An integration that allows managed Composio write actions is operator-only. AgentKit blocks its generated tool during model-driven chat, channel, and eval runs. Review the exact action, invoke it directly with `agentkit tool`, and pass `confirmed: true` for writes. `confirmExternalWrites: false` disables only that secondary input check, not the operator-only permission boundary.
 
 ## Testability
 

package/src/templates/skills/agentkit-security/SKILL.md

@@ -38,6 +38,8 @@ skills/
 - Tools receive only secrets listed in that tool's `secrets` field.
 - Prefer `ctx.secrets` over direct `process.env` reads in tools.
 - Add `permissions` for external capabilities.
+- Use a `:read` suffix only for read-only capabilities. AgentKit requires direct operator invocation for every other declared permission.
+- Treat Capsule config, tools, evals, and sync modules as trusted executable TypeScript; local AgentKit commands do not sandbox them.
 - Add timeouts to network tools.
 - Remove client PII before writing evals.
 - Keep `.agentkit/improve/` bundles out of commits and review generated regression evals before committing.

package/src/templates/skills/agentkit-tools/SKILL.md

@@ -7,15 +7,19 @@ description: Use when adding, changing, registering, or testing AgentKit TypeScr
 
 Use this when the agent needs code, an API, live data, a write, or an external action.
 
+When the owner asks to use TypeSafe/Jev for a capsule capability, follow `docs/guides/use-jev.md` from the installed docs path (`npm run agentkit -- docs path`) and [the Jev tool example](examples/jev-service-fit.tool.md). Implement the requested judgment in a normal capsule tool; adapt its questions and criteria to the brief.
+
 ## Workflow
 
 1. Create or edit `tools/<name>.ts`.
 2. Export a `defineTool` tool with `name`, `description`, `inputSchema`, and usually `outputSchema`.
 3. Add `secrets`, `permissions`, and `timeoutMs` when needed.
+   - End read-only permissions with `:read`.
+   - Non-read permissions are operator-only: chat, channels, and evals cannot execute them automatically.
 4. Register the tool in `agentkit.config.ts`.
 5. Keep secret names in `.env.schema`; values stay in ignored `.env` or hosted managed secrets.
 6. Use `ctx.clock` for date-sensitive tool logic instead of calling `new Date()` directly.
-7. Add eval guards for destructive or external side effects.
+7. Verify destructive or external side effects through a reviewed direct `agentkit tool` invocation; evals should assert that automatic execution is blocked.
 8. Add deterministic fixtures, fake branches, or direct tool inputs for important success and failure paths.
 9. Add evals that assert the tool is called with safe inputs, or not called when confirmation/intake is missing.
 

package/src/templates/skills/agentkit-tools/examples/eval-safe-external-action.tool.md

@@ -7,23 +7,18 @@ import { defineTool } from "@andreprado/agentkit";
 
 export const sendFollowupEmail = defineTool({
   name: "send_followup_email",
-  description: "Sends a follow-up email after explicit confirmation.",
+  description: "Sends a follow-up email after explicit operator review.",
   secrets: ["EMAIL_API_KEY"],
   permissions: ["email:send"],
   inputSchema: {
     type: "object",
     properties: {
       email: { type: "string" },
-      confirmed: { type: "boolean" },
     },
-    required: ["email", "confirmed"],
+    required: ["email"],
     additionalProperties: false,
   },
-  async execute(input: { email: string; confirmed: boolean }, ctx) {
-    if (!input.confirmed) {
-      return { sent: false, reason: "confirmation_required" };
-    }
-
+  async execute(input: { email: string }, ctx) {
     if (ctx.runtime.environment === "eval") {
       return { sent: false, evalFixture: true, email: input.email };
     }
@@ -35,3 +30,8 @@ export const sendFollowupEmail = defineTool({
 });
 ```
 
+Because `email:send` is not a `:read` permission, AgentKit rejects model-driven chat, channel, and eval calls before `execute` runs. After reviewing the exact recipient, the operator can invoke it directly:
+
+```sh
+npm run agentkit -- tool send_followup_email --input '{"email":"client@example.com"}'
+```