@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.20

package/docs/llms.txt

@@ -2,56 +2,105 @@
 
 AgentKit creates and runs Agent Capsules: folders with `agentkit.config.ts`, prompts, tools, evals, local storage, and agent-facing docs.
 
-Read `docs/llms-full.txt` when you need the whole operating contract.
+Read `docs/llms-full.txt` only when you need the whole operating contract.
 
 Task guides:
 
 - Create a capsule: `docs/guides/create-agent.md`
 - Add a TypeScript tool: `docs/guides/add-tool.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`
+- 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 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`
 - Follow secret, access, and tool safety rules: `docs/guides/security-rules.md`
 
 Current local commands:
 
 ```sh
-agentkit new <name> --template blank|support
+agentkit new <name> --template blank|support|dentista
+agentkit new <name> --template blank --no-install
 agentkit docs full
+agentkit env set <NAME> --stdin
 agentkit env list
 agentkit env unset <NAME>
 agentkit handoff codex|claude [goal]
 agentkit chat --message "hello"
 agentkit tool <name> --input <path-or-json>
+agentkit knowledge add <path-or-url>
+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 discord support-discord
+agentkit channels connect discord server-discord --mode bot
+agentkit channels connect slack support-slack
 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
+agentkit deploy --smoke "hello"
 agentkit deploy status
+agentkit deploy smoke --message "hello"
+agentkit chat-ui --deploy
+agentkit secret set <NAME> --from-local-env
+agentkit secret sync --from-local
 agentkit secret list
-agentkit access token create website-chat
+agentkit access token create website-chat --out .agentkit/website-chat-access-token.json
 agentkit access token list
 agentkit inspect
 agentkit dev
+agentkit open
 ```
 
-Generated capsules include `AGENTKIT.md` and `AGENTS.md` so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately. `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.
+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 wizard or recipe layer: 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.
+
+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, 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.
+
+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`:
 
@@ -60,6 +109,7 @@ GET  /_agentkit
 POST /v1/chat
 GET  /v1/conversations
 GET  /v1/conversations/:id
+GET  /v1/conversations/:id/trace
 ```
 
-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.
+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.2",
+  "version": "0.1.0-alpha.20",
   "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": {
@@ -35,8 +32,8 @@
   "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",
-    "postgres": "^3.4.9",
     "tsx": "^4.22.3",
     "typebox": "^1.1.38"
   },

package/src/cli/args.ts

@@ -0,0 +1,57 @@
+export type ParsedArgs = {
+  command?: string;
+  positional: string[];
+  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[] = [];
+  const flags: Record<string, string | boolean> = {};
+
+  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 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 && (dashPrefixedValueFlags.has(name) || !next.startsWith("--"))) {
+      flags[name] = next;
+      index += 1;
+    } else {
+      flags[name] = true;
+    }
+  }
+
+  return { command, positional, flags };
+}
+
+export function isHelpRequested(args: ParsedArgs): boolean {
+  return args.flags.help === true || args.flags.h === true || args.positional.includes("--help") || args.positional.includes("-h");
+}

package/src/cli/cloud-client.ts

@@ -0,0 +1,377 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { AgentKitError } from "../runtime/errors";
+import { defaultAgentKitCloudApiUrl } from "./constants";
+import { parseCloudApiUrl } from "./flags";
+
+export type CloudAuthConfig = {
+  apiUrl: string;
+  token: string;
+  source?: "environment" | "file";
+};
+
+export type CloudMeResponse = {
+  account?: {
+    email?: string;
+    status?: string;
+  };
+};
+
+export type CloudCapabilitiesResponse = {
+  capabilities?: Array<{
+    name?: string;
+    status?: string;
+  }>;
+};
+
+export type CloudLimitsResponse = {
+  online_agents?: {
+    account?: {
+      used?: number | null;
+      limit?: number | null;
+    };
+    global?: {
+      used?: number | null;
+      limit?: number | null;
+    };
+  };
+};
+
+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;
+  };
+};
+
+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;
+    status?: string;
+    updated_at?: string;
+  }>;
+};
+
+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");
+}
+
+export async function readCloudAuth(): Promise<CloudAuthConfig | null> {
+  if (process.env.AGENTKIT_CLOUD_API_TOKEN) {
+    return {
+      apiUrl: process.env.AGENTKIT_CLOUD_API_URL ?? defaultAgentKitCloudApiUrl,
+      token: process.env.AGENTKIT_CLOUD_API_TOKEN,
+      source: "environment",
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(await readFile(cloudAuthPath(), "utf8"));
+
+    if (parsed && typeof parsed === "object" && typeof parsed.token === "string") {
+      return {
+        apiUrl: typeof parsed.apiUrl === "string" ? parsed.apiUrl : defaultAgentKitCloudApiUrl,
+        token: parsed.token,
+        source: "file",
+      };
+    }
+  } catch {
+    return 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> {
+  await rm(cloudAuthPath(), { force: true });
+}
+
+export async function resolveCloudApiUrl(flag: string | boolean | undefined): Promise<string> {
+  if (flag !== undefined) {
+    return parseCloudApiUrl(flag);
+  }
+
+  const auth = await readCloudAuth();
+  return auth?.apiUrl ?? parseCloudApiUrl(undefined);
+}
+
+export async function verifyCloudLogin(
+  apiUrl: string,
+  token: string,
+): Promise<{ me: CloudMeResponse; capabilities: CloudCapabilitiesResponse }> {
+  const me = await cloudApiRequestWithToken<CloudMeResponse>(apiUrl, "/v1/me", token, { method: "GET" });
+  const capabilities = await cloudApiRequestWithToken<CloudCapabilitiesResponse>(
+    apiUrl,
+    "/v1/me/capabilities",
+    token,
+    { method: "GET" },
+  );
+
+  return { me, capabilities };
+}
+
+export async function cloudGet<T>(apiUrl: string, path: string): Promise<T> {
+  const response = await cloudFetch(apiUrl, path);
+  const payload = await response.json();
+
+  if (!response.ok) {
+    throw new Error(readCloudError(payload, response.status));
+  }
+
+  return payload as T;
+}
+
+export async function cloudPost<T>(apiUrl: string, path: string, body: unknown): Promise<T> {
+  const response = await cloudFetch(apiUrl, path, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const payload = await response.json();
+
+  if (!response.ok) {
+    throw new Error(readCloudError(payload, response.status));
+  }
+
+  return payload as T;
+}
+
+export async function cloudFetch(apiUrl: string, path: string, init: RequestInit = {}): Promise<Response> {
+  const headers = new Headers(init.headers);
+  const auth = await readCloudAuthForApiUrl(apiUrl);
+  const apiToken = auth?.token;
+
+  if (apiToken && !headers.has("Authorization")) {
+    headers.set("Authorization", `Bearer ${apiToken}`);
+  }
+
+  return fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {
+    ...init,
+    headers,
+  });
+}
+
+function cloudAuthMatchesApiUrl(auth: CloudAuthConfig, apiUrl: string): boolean {
+  return parseCloudApiUrl(auth.apiUrl) === parseCloudApiUrl(apiUrl);
+}
+
+export async function cloudApiRequest(apiUrl: string, path: string, init: RequestInit): Promise<unknown> {
+  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 (apiToken && !headers.has("Authorization")) {
+    headers.set("Authorization", `Bearer ${apiToken}`);
+  }
+
+  const response = await fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {
+    ...init,
+    headers,
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    const code =
+      payload && typeof payload === "object" && "error" in payload
+        ? String((payload as { error?: { code?: unknown } }).error?.code ?? "cloud_request_failed")
+        : "cloud_request_failed";
+    let message = readCloudError(payload, response.status);
+
+    if (code === "auth_token_invalid") {
+      message = `${message} Token source: ${auth ? formatCloudAuthSource(auth) : "none"}. Run: agentkit login --token <token>`;
+    }
+
+    throw new AgentKitError(code, message);
+  }
+
+  return payload;
+}
+
+export async function cloudApiRequestWithToken<T>(
+  apiUrl: string,
+  path: string,
+  token: string,
+  init: RequestInit,
+): Promise<T> {
+  const headers = new Headers(init.headers);
+
+  if (!headers.has("Content-Type") && init.body !== undefined) {
+    headers.set("Content-Type", "application/json");
+  }
+
+  headers.set("Authorization", `Bearer ${token}`);
+
+  const response = await fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {
+    ...init,
+    headers,
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    const code =
+      payload && typeof payload === "object" && "error" in payload
+        ? String((payload as { error?: { code?: unknown } }).error?.code ?? "cloud_request_failed")
+        : "cloud_request_failed";
+    throw new AgentKitError(code, readCloudError(payload, response.status));
+  }
+
+  return payload as T;
+}
+
+export function readCloudError(payload: unknown, status: number): string {
+  if (payload && typeof payload === "object" && "error" in payload) {
+    const error = (payload as { error?: { message?: unknown } }).error;
+    if (typeof error?.message === "string") {
+      return error.message;
+    }
+  }
+
+  return `AgentKit Cloud request failed with HTTP ${status}.`;
+}
+
+export function formatCloudAuthSource(auth: CloudAuthConfig): string {
+  if (auth.source === "environment") {
+    return "AGENTKIT_CLOUD_API_TOKEN";
+  }
+
+  if (auth.source === "file") {
+    return cloudAuthPath();
+  }
+
+  return "AgentKit Cloud auth";
+}