@andreprado/agentkit 0.1.0-alpha.9 → 0.1.0

package/docs/llms.txt

@@ -8,27 +8,37 @@ 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`
+- Replay collected traces locally: `docs/guides/replay-production-traces.md`
+- Send AgentKit product feedback safely: `docs/guides/send-feedback.md`
 - Switch from `test/fake` to a real provider: `docs/guides/use-provider.md`
 - Prepare for hosted deploy: `docs/guides/prepare-deploy.md`
 - Build Cloudflare artifact: `agentkit build --target cloudflare`
 - Build container artifact: `agentkit build --target container`
 - Generate VPS handoff: `agentkit deploy --target vps --host agent.example.com --dry-run`
 - Add hosted channels: `docs/guides/add-channel.md`
+- Route replies across channels or add generic output webhooks: `docs/guides/add-channel.md#reply-through-another-channel`
+- Add AgentKit-managed Composio: `docs/guides/add-managed-composio.md`
 - Buffer rapid channel messages: `docs/guides/add-channel.md#buffer-bursty-messages`
+- Connect Discord: `docs/guides/connect-discord.md`
+- Connect Slack: `docs/guides/connect-slack.md`
 - Connect Telegram: `docs/guides/connect-telegram.md`
+- Connect WhatsApp through Evolution API: `docs/guides/connect-whatsapp-evolution.md`
+- Connect WhatsApp through UAZAPI: `docs/guides/connect-whatsapp-uazapi.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Follow channel webhook and delivery-log safety rules: `docs/guides/channel-security.md`
-- Prepare Channels for production: `docs/guides/channels-production-handoff.md`
+- Debug channel delivery and cross-channel reply routing: `docs/guides/debug-channel.md`
 - Follow secret, access, and tool safety rules: `docs/guides/security-rules.md`
-- Plan repo-local skills for coding agents: `docs/guides/agentkit-skills-architecture.md`
 
 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
@@ -41,15 +51,37 @@ agentkit knowledge sync
 agentkit knowledge inspect
 agentkit knowledge search <query> [--top-k <number>]
 agentkit eval run
+agentkit improve collect --deploy --since 24h
+agentkit improve evals .agentkit/improve/<run>
+agentkit replay .agentkit/improve/<run> --against local
+agentkit feedback create --about last-run --kind bug --summary "what failed"
+agentkit feedback send .agentkit/feedback/<draft>.json
 agentkit conversations list
 agentkit conversations show <conversation-id>
+agentkit conversations trace <conversation-id> [--deploy]
 agentkit channels list
 agentkit channels add telegram support-telegram
+agentkit channels connect whatsapp main-whatsapp --provider evolution
+agentkit channels connect whatsapp support-whatsapp --provider uazapi
+agentkit channels connect discord support-discord
+agentkit channels connect discord server-discord --mode bot
+agentkit channels connect slack support-slack
+agentkit channels connect webhook n8n-webhook
 agentkit channels setup support-telegram
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"
+agentkit channels test-audio support-telegram --fixture voice-note
+agentkit transcribe smoke --provider groq
 agentkit channels deliveries list support-telegram
+agentkit integrations status [--toolkit googlecalendar]
+agentkit integrations connect composio --toolkit gmail
+agentkit skills status
+agentkit skills sync
+agentkit billing checkout --slots 1 --email user@example.com
+agentkit billing claim billint_... --secret bsec_...
 agentkit login --token agk_user_...
+agentkit account token create new-laptop --use
+agentkit account token list
 agentkit deploy doctor
 agentkit deploy --smoke "hello"
 agentkit deploy status
@@ -65,11 +97,21 @@ agentkit dev
 agentkit open
 ```
 
-Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/` pack so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately without loading the full contract by default. Start with `skills/agentkit-capsule/SKILL.md`, then load the task skill for the current work. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold and contract.
+On Windows PowerShell, if `npm.ps1` or `npx.ps1` is blocked with `PSSecurityException`, run capsule scripts through the `.cmd` shims, for example `npm.cmd run agentkit -- inspect`, `npm.cmd run agentkit -- knowledge sync`, or `npm.cmd run eval`.
+
+Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/` pack so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately without loading the full contract by default. Start with `skills/agentkit-capsule/SKILL.md`, then load the task skill for the current work. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no AgentKit CLI wizard in the normal flow: the coding agent edits the capsule directly from the scaffold and contract.
 
 UI testing is part of the handoff. For local UI testing, run `agentkit dev`, open the printed `Chat:` URL, and tell the owner the exact URL. After hosted deploy, run `agentkit chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the deploy.
 
-`test/fake` is deterministic and validates scaffold, direct tool calls, and fake-provider evals. It does not validate natural conversation quality. Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
+Hosted Chat UI shows the current conversation id, tool calls, tool errors, and a new-conversation control. Use `agentkit conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy.
+
+`test/fake` is deterministic and validates scaffold, direct tool calls, and fake-provider evals. It does not validate natural conversation quality. Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them.
+
+For OpenRouter, prefer model ids or aliases known to the installed Pi SDK, such as `~google/gemini-flash-latest`. If an OpenRouter id is newer than Pi's registry, AgentKit passes the raw id through to OpenRouter with conservative unknown-model metadata; OpenRouter can still reject invalid, inaccessible, or unsupported models.
+
+For OpenCode Zen, use `provider: { name: "opencode", model: "big-pickle" }`. For OpenCode Go, use `provider: { name: "opencode-go", model: "deepseek-v4-flash" }`. Both use `OPENCODE_API_KEY` in `secrets` and `.env.schema`.
+
+AgentKit injects the current ISO timestamp, local date, weekday, local date/time, and timezone dynamically into every chat run. Set `timeZone` in `agentkit.config.ts` for scheduling agents so "today", "tomorrow", and weekdays resolve in the business/user timezone; otherwise AgentKit falls back to `AGENTKIT_TIME_ZONE`, valid `TZ`, then the runtime default. Do not hardcode today's date in prompts.
 
 Current local endpoints from `agentkit dev`:
 
@@ -78,6 +120,11 @@ GET  /_agentkit
 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
 ```
 
-Local `.env` is for development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted alpha deploys require `cloudflare_deploy_alpha` through `agentkit login --token ...`; production uses managed secrets in the hosted contract.
+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.9",
+  "version": "0.1.0",
   "private": false,
   "type": "module",
   "repository": {
@@ -18,9 +18,6 @@
     "!src/**/*.test.ts",
     "!src/runtime/fixtures",
     "docs",
-    "!docs/guides/backend-contracts.md",
-    "!docs/guides/debug-channel.md",
-    "!docs/guides/deploy-agentkit-cloud-hostinger.md",
     "README.md"
   ],
   "publishConfig": {
@@ -34,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/args.ts

@@ -4,6 +4,15 @@ export type ParsedArgs = {
   flags: Record<string, string | boolean>;
 };
 
+const dashPrefixedValueFlags = new Set([
+  "brief",
+  "input",
+  "input-json",
+  "message",
+  "prompt",
+  "smoke",
+]);
+
 export function parseArgs(argv: string[]): ParsedArgs {
   const [command, ...rest] = argv;
   const positional: string[] = [];
@@ -12,15 +21,27 @@ export function parseArgs(argv: string[]): ParsedArgs {
   for (let index = 0; index < rest.length; index += 1) {
     const value = rest[index];
 
+    if (value === "--") {
+      positional.push(...rest.slice(index + 1));
+      break;
+    }
+
     if (!value.startsWith("--")) {
       positional.push(value);
       continue;
     }
 
-    const name = value.slice(2);
+    const equalsIndex = value.indexOf("=");
+    const name = equalsIndex === -1 ? value.slice(2) : value.slice(2, equalsIndex);
+
+    if (equalsIndex !== -1) {
+      flags[name] = value.slice(equalsIndex + 1);
+      continue;
+    }
+
     const next = rest[index + 1];
 
-    if (next && !next.startsWith("--")) {
+    if (next && (dashPrefixedValueFlags.has(name) || !next.startsWith("--"))) {
       flags[name] = next;
       index += 1;
     } else {

package/src/cli/cloud-client.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -39,12 +39,37 @@ export type CloudLimitsResponse = {
   };
 };
 
+export type CloudManagedComposioResponse = {
+  managed_composio?: {
+    entitlement?: "active" | "missing" | string;
+    api_key?: "set" | "missing" | string;
+    toolkits?: Array<{
+      toolkit?: string;
+      auth_config_env?: string;
+      auth_config?: "set" | "missing" | string;
+      auth_config_source?: "project" | "account" | "global" | "env" | string;
+    }>;
+  };
+};
+
+export type CloudProjectResolveResponse = {
+  project?: {
+    id?: string;
+    name?: string;
+    owner_state?: "anonymous" | "claimed";
+  };
+};
+
 export type DeployAccessTokenCreateResponse = {
   access_token?: {
     id?: string;
     deploy_id?: string;
+    account_id?: string;
     name?: string;
     token?: string;
+    created_at?: string;
+    expires_at?: string;
+    last_used_at?: string;
   };
 };
 
@@ -52,10 +77,76 @@ export type DeployAccessTokenListResponse = {
   access_tokens?: Array<{
     id?: string;
     deploy_id?: string;
+    account_id?: string;
     name?: string;
+    created_at?: string;
+    expires_at?: string;
+    last_used_at?: string;
   }>;
 };
 
+export type AccountApiTokenCreateResponse = {
+  token?: {
+    id?: string;
+    account_id?: string;
+    name?: string;
+    token?: string;
+    created_at?: string;
+    expires_at?: string;
+    last_used_at?: string;
+  };
+};
+
+export type AccountApiTokenListResponse = {
+  tokens?: Array<{
+    id?: string;
+    account_id?: string;
+    name?: string;
+    created_at?: string;
+    expires_at?: string;
+    last_used_at?: string;
+    revoked_at?: string;
+  }>;
+};
+
+export type BillingCheckoutResponse = {
+  checkout?: {
+    id?: string;
+    url?: string;
+  };
+  billing_intent?: {
+    id?: string;
+    account_id?: string;
+    email?: string;
+    requested_slots?: number;
+    status?: string;
+    secret?: string;
+  };
+};
+
+export type BillingCheckoutIntentResponse = {
+  billing_intent?: {
+    id?: string;
+    account_id?: string;
+    email?: string;
+    requested_slots?: number;
+    status?: string;
+    checkout_session_id?: string;
+    stripe_customer_id?: string;
+    stripe_subscription_id?: string;
+    completed_at?: string;
+    token_claimed_at?: string;
+  };
+};
+
+export type BillingClaimResponse = BillingCheckoutIntentResponse & AccountApiTokenCreateResponse;
+
+export type BillingPortalResponse = {
+  portal?: {
+    url?: string;
+  };
+};
+
 export type CloudSecretsResponse = {
   secrets?: Array<{
     name?: string;
@@ -64,6 +155,18 @@ export type CloudSecretsResponse = {
   }>;
 };
 
+export type FeedbackSendResponse = {
+  feedback?: {
+    id?: string;
+    account_id?: string;
+    kind?: string;
+    summary?: string;
+    status?: string;
+    client_report_id?: string;
+    created_at?: string;
+  };
+};
+
 export function cloudAuthPath(): string {
   return join(homedir(), ".agentkit", "cloud.json");
 }
@@ -94,9 +197,20 @@ export async function readCloudAuth(): Promise<CloudAuthConfig | null> {
   return null;
 }
 
+export async function readCloudAuthForApiUrl(apiUrl: string): Promise<CloudAuthConfig | null> {
+  const auth = await readCloudAuth();
+
+  if (auth?.source === "file" && !cloudAuthMatchesApiUrl(auth, apiUrl)) {
+    return null;
+  }
+
+  return auth;
+}
+
 export async function writeCloudAuth(config: CloudAuthConfig): Promise<void> {
   await mkdir(join(homedir(), ".agentkit"), { recursive: true });
   await writeFile(cloudAuthPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  await chmod(cloudAuthPath(), 0o600);
 }
 
 export async function clearCloudAuth(): Promise<void> {
@@ -155,11 +269,8 @@ export async function cloudPost<T>(apiUrl: string, path: string, body: unknown):
 
 export async function cloudFetch(apiUrl: string, path: string, init: RequestInit = {}): Promise<Response> {
   const headers = new Headers(init.headers);
-  const auth = await readCloudAuth();
-  const apiToken =
-    auth?.source === "file" && !cloudAuthMatchesApiUrl(auth, apiUrl)
-      ? undefined
-      : auth?.token;
+  const auth = await readCloudAuthForApiUrl(apiUrl);
+  const apiToken = auth?.token;
 
   if (apiToken && !headers.has("Authorization")) {
     headers.set("Authorization", `Bearer ${apiToken}`);
@@ -176,15 +287,16 @@ function cloudAuthMatchesApiUrl(auth: CloudAuthConfig, apiUrl: string): boolean
 }
 
 export async function cloudApiRequest(apiUrl: string, path: string, init: RequestInit): Promise<unknown> {
-  const auth = await readCloudAuth();
+  const auth = await readCloudAuthForApiUrl(apiUrl);
   const headers = new Headers(init.headers);
+  const apiToken = auth?.token;
 
   if (!headers.has("Content-Type") && init.body !== undefined) {
     headers.set("Content-Type", "application/json");
   }
 
-  if (auth?.token && !headers.has("Authorization")) {
-    headers.set("Authorization", `Bearer ${auth.token}`);
+  if (apiToken && !headers.has("Authorization")) {
+    headers.set("Authorization", `Bearer ${apiToken}`);
   }
 
   const response = await fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {