@andreprado/agentkit 0.1.0-alpha.10

package/docs/llms.txt

@@ -0,0 +1,83 @@
+# AgentKit LLM Index
+
+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` 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`
+- 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`
+- Buffer rapid channel messages: `docs/guides/add-channel.md#buffer-bursty-messages`
+- 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`
+- 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 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 conversations list
+agentkit conversations show <conversation-id>
+agentkit channels list
+agentkit channels add telegram support-telegram
+agentkit channels setup support-telegram
+agentkit channels status support-telegram
+agentkit channels test support-telegram --message "hello"
+agentkit channels deliveries list support-telegram
+agentkit login --token agk_user_...
+agentkit deploy doctor
+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 --out .agentkit/website-chat-access-token.json
+agentkit access token list
+agentkit inspect
+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.
+
+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.
+
+Current local endpoints from `agentkit dev`:
+
+```txt
+GET  /_agentkit
+POST /v1/chat
+GET  /v1/conversations
+GET  /v1/conversations/:id
+```
+
+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.

package/docs/portable-deploy-release-checklist.md

@@ -0,0 +1,41 @@
+# Portable Deploy Release Checklist
+
+Run this before merging portable deploy target work.
+
+## Tests
+
+```sh
+bun test
+npm run typecheck
+npm run agentkit -- build --target cloudflare
+npm run agentkit -- build --target container
+npm run agentkit -- deploy --target vps --host agent.example.com --dry-run
+docker compose -f .agentkit/build/vps/compose.yaml config
+```
+
+## Smoke
+
+- Cloudflare build contains `worker.js`, `wrangler.jsonc`, `durable-object-schema.sql`, and `agent.manifest.json`.
+- Container build contains `server.js`, `Dockerfile`, `migrations/`, and `agent.manifest.json`.
+- VPS build contains `compose.yaml`, `.env.production.example`, `SECRETS.md`, and `PRODUCTION_HANDOFF.md`.
+- `/health`, `/_agentkit`, `/chat`, `/tools/:name`, `/files/:key`, and channel webhook fixtures pass on the local/container runtime.
+
+## Secrets
+
+```sh
+rg -n "sk-|OPENAI_API_KEY=.*[A-Za-z0-9]" .agentkit/build || true
+```
+
+Expected: no secret values. Generated files may contain secret names only.
+
+## Production Handoff
+
+- Cloudflare deploy has target-aware `.agentkit/deploy.json` with `target`, `runtime`, and `resources`.
+- VPS handoff documents `PORT`, `AGENTKIT_SQLITE_PATH`, reverse proxy expectations, smoke checks, SQLite backup, Postgres upgrade path, and rollback.
+- Rollback command is present in `.agentkit/build/vps/PRODUCTION_HANDOFF.md`.
+
+## External Smokes
+
+- Cloudflare deployed smoke requires Cloudflare credentials and a provider key.
+- Docker image smoke requires a running Docker daemon.
+- Telegram/Zapster real send smoke requires explicit provider credentials.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@andreprado/agentkit",
+  "version": "0.1.0-alpha.10",
+  "private": false,
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrehfp/agentkit.git",
+    "directory": "packages/agentkit"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./runtime/container": "./src/runtime/targets/container/server.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!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": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "agentkit": "bin/agentkit.mjs"
+  },
+  "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",
+    "typebox": "^1.1.38"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "bun-types": "^1.3.0"
+  }
+}

package/src/cli/args.ts

@@ -0,0 +1,36 @@
+export type ParsedArgs = {
+  command?: string;
+  positional: string[];
+  flags: Record<string, string | boolean>;
+};
+
+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.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+
+    const name = value.slice(2);
+    const next = rest[index + 1];
+
+    if (next && !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,265 @@
+import { 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 DeployAccessTokenCreateResponse = {
+  access_token?: {
+    id?: string;
+    deploy_id?: string;
+    name?: string;
+    token?: string;
+  };
+};
+
+export type DeployAccessTokenListResponse = {
+  access_tokens?: Array<{
+    id?: string;
+    deploy_id?: string;
+    name?: string;
+  }>;
+};
+
+export type CloudSecretsResponse = {
+  secrets?: Array<{
+    name?: string;
+    status?: string;
+    updated_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 writeCloudAuth(config: CloudAuthConfig): Promise<void> {
+  await mkdir(join(homedir(), ".agentkit"), { recursive: true });
+  await writeFile(cloudAuthPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 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 readCloudAuth();
+  const apiToken =
+    auth?.source === "file" && !cloudAuthMatchesApiUrl(auth, apiUrl)
+      ? undefined
+      : 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 readCloudAuth();
+  const headers = new Headers(init.headers);
+
+  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}`);
+  }
+
+  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";
+}