@andreprado/agentkit 0.1.0-alpha.3 → 0.1.0-alpha.5

package/docs/llms-full.txt

@@ -30,55 +30,65 @@ The capsule root is the runtime boundary. Run AgentKit commands from the directo
 
 ## Current Command Surface
 
-Implemented local commands:
+Current commands:
 
 ```sh
-agentkit new <name> --template blank
-agentkit new <name> --template support
-agentkit new <name> --template blank --no-install
-agentkit chat --message "hello"
-agentkit tool <name> --input <path-or-json>
+agentkit new <name> [--template blank|support|dentista] [--no-install]
+agentkit dev [--port <number>]
+agentkit open
+agentkit chat-ui --deploy
+agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
+agentkit chat --message <text> [--conversation-id <id>]
+agentkit tool <name> [--input <path-or-json>]
+agentkit db migrate
+agentkit db reset --yes
+agentkit db shell
+agentkit db seed [--file <path>]
 agentkit eval run
 agentkit conversations list
 agentkit conversations show <conversation-id>
 agentkit channels list
-agentkit channels add website website-chat
-agentkit channels add telegram support-telegram
-agentkit channels add whatsapp support-whatsapp --provider zapster
-agentkit channels setup <name>
-agentkit channels setup <name> --apply
-agentkit channels status <name>
-agentkit channels test <name> --message "hello"
-agentkit channels test <name> --fixture ./fixtures/provider-event.json
-agentkit channels deliveries list <name>
-agentkit channels deliveries show <delivery-id>
+agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
+agentkit channels setup <name> [--apply] [--api <url>]
+agentkit channels status <name> [--api <url>]
+agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
+agentkit channels deliveries list <name> [--api <url>]
+agentkit channels deliveries show <delivery-id> [--api <url>]
 agentkit inspect
-agentkit env set <NAME> <VALUE>
-agentkit env list
-agentkit env unset <NAME>
-agentkit docs path
-agentkit docs llms
-agentkit docs full
-agentkit handoff codex [goal]
-agentkit handoff claude [goal]
-agentkit dev
-agentkit dev --port 4124
-agentkit build
-agentkit deploy
-agentkit deploy --dry-run
+agentkit build [--target cloudflare|container]
 agentkit login --token <token>
 agentkit logout
+agentkit deploy [--target cloudflare|vps] [--host <host>] [--api <url>] [--dry-run] [--anonymous] [--local-wrangler] [--smoke <message>]
+agentkit deploy doctor [--api <url>] [--anonymous]
+agentkit deploy smoke [--message <text>] [--api <url>]
 agentkit deploy status
 agentkit deploy pause
 agentkit deploy resume
 agentkit secret set <NAME> <VALUE>
+agentkit secret set <NAME> --stdin
+agentkit secret set <NAME> --from-env [ENV_NAME]
+agentkit secret set <NAME> --from-local-env
+agentkit secret sync --from-local
 agentkit secret list
 agentkit secret unset <NAME>
-agentkit access token create <name>
+agentkit access token create <name> [--api <url>] [--out <path>]
 agentkit access token list
 agentkit access token revoke <token-id>
+agentkit env set <NAME> <VALUE>
+agentkit env set <NAME> --stdin
+agentkit env set <NAME> --from-env [ENV_NAME]
+agentkit env list
+agentkit env unset <NAME>
+agentkit docs path
+agentkit docs llms
+agentkit docs full
+agentkit handoff codex [goal]
+agentkit handoff claude [goal]
+agentkit help commands
 ```
 
+Prefer `env set --stdin` or `--from-env` for local secret values, and prefer `secret set --stdin`, `--from-env`, or `--from-local-env` for hosted secrets. Inline `<VALUE>` forms exist for simple non-sensitive values, but agents should avoid putting secrets in shell history.
+
 Planned commands described by the contract but not implemented yet:
 
 ```sh
@@ -125,7 +135,7 @@ Then open the folder in Codex, Claude Code, or another coding agent and ask dire
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, and `tools/`, then run the verification commands before finishing.
+The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, `schema.sql`, `tools/`, and `evals/`, then run the verification commands before finishing. Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; the coding agent implements directly in the capsule.
 
 Optional handoff shortcut:
 
@@ -136,6 +146,8 @@ npm run agentkit -- handoff claude "Develop an appointment and intake agent for
 
 The command prints a ready-to-paste prompt that points the coding agent at `AGENTKIT.md` and the packaged `llms-full.txt` contract.
 
+The generated docs and handoff prompt must make UI testing explicit. For local UI testing, run `npm run dev`, open the printed `Chat:` URL, and tell the owner the exact URL. For hosted UI testing after deploy, run `npm run agentkit -- chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the hosted deploy.
+
 ## Agent Config
 
 `agentkit.config.ts` is the source of truth:
@@ -202,7 +214,11 @@ provider: {
 secrets: [],
 ```
 
-Use OpenAI locally:
+`test/fake` is deterministic. It is useful for scaffold checks, direct tool checks, and fake-provider evals, but 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. After the owner chooses, update `agentkit.config.ts`, `.env.schema`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
+
+OpenAI example:
 
 ```ts
 provider: {
@@ -539,6 +555,8 @@ Run:
 agentkit dev
 ```
 
+If the default local port is occupied, `agentkit dev` chooses the next available port and prints the actual URLs. If the occupied port is another AgentKit server, the output names the agent using it.
+
 Expected output:
 
 ```txt
@@ -550,6 +568,12 @@ Inspect:   http://localhost:4123/_agentkit
 Storage:   .agentkit/agentkit.db
 ```
 
+To reopen the local UI for the current capsule after the server is already running:
+
+```sh
+agentkit open
+```
+
 Endpoints:
 
 ```txt
@@ -567,6 +591,8 @@ curl -X POST http://localhost:4123/v1/chat \
   -d '{"message":{"role":"user","content":"hello"}}'
 ```
 
+The chat response includes `conversationId`. Send the same `conversationId` on the next `POST /v1/chat` request, or pass it to `agentkit chat --conversation-id <id>`, to continue with the persisted message history.
+
 ## Conversations
 
 After chat:
@@ -610,6 +636,8 @@ persisted_tool_call
 
 `persisted_tool_call` validates the tool call saved in local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `status`, and/or `visibility`. `tool_call` remains accepted as a backwards-compatible alias.
 
+Evals run the normal capsule tools. If a tool would write externally, delete, charge money, send email, or call a real customer system, make its `execute` implementation branch on `ctx.runtime.environment === "eval"` and return deterministic non-destructive output for eval runs. Do not invent an eval-only mock API; keep the behavior inside the registered tool contract unless AgentKit adds a first-class mock facility later.
+
 ## Security Rules
 
 Never commit:
@@ -633,7 +661,7 @@ prompts/
 docs/
 ```
 
-Local `.env` is development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted alpha deploys use `agentkit login --token ...` and managed secrets through `agentkit secret set/list/unset`.
+Local `.env` is development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted alpha deploys use `agentkit login --token ...` and managed secrets through `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.
 
@@ -647,18 +675,21 @@ Current flow:
 agentkit deploy --dry-run
 agentkit login --token agk_user_...
 agentkit deploy doctor
-agentkit deploy
+agentkit deploy --smoke "hello"
 agentkit deploy status
+agentkit deploy smoke --message "hello"
+agentkit chat-ui --deploy
 ```
 
-`agentkit deploy doctor` checks AgentKit Cloud login, `cloudflare_deploy_alpha`, hosted secrets, local `.env` names that still need `agentkit secret set`, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, and writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json` for private hosted deploys. Production alpha deploys require an account with `cloudflare_deploy_alpha`; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
+`agentkit deploy doctor` checks AgentKit Cloud login, `cloudflare_deploy_alpha`, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, and writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json` for private hosted deploys. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code. Production alpha deploys require an account with `cloudflare_deploy_alpha`; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
 
 The CLI defaults to the hosted AgentKit Cloud API at `https://agentkit-cloud.aibuilders.com.br`. Use `AGENTKIT_CLOUD_API_URL` or `agentkit deploy --api <url>` only for local or alternate control-plane tests.
 
 Account/access flow:
 
 ```sh
-agentkit secret set OPENAI_API_KEY
+agentkit secret set OPENAI_API_KEY --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

package/docs/llms.txt

@@ -24,9 +24,10 @@ Task guides:
 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]
@@ -43,16 +44,25 @@ agentkit channels test support-telegram --message "hello"
 agentkit channels deliveries list support-telegram
 agentkit login --token agk_user_...
 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 --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.
+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. 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`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "private": false,
   "type": "module",
   "repository": {

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,257 @@
+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 function cloudFetch(apiUrl: string, path: string, init: RequestInit = {}): Promise<Response> {
+  const headers = new Headers(init.headers);
+  const apiToken = process.env.AGENTKIT_CLOUD_API_TOKEN;
+
+  if (apiToken && !headers.has("Authorization")) {
+    headers.set("Authorization", `Bearer ${apiToken}`);
+  }
+
+  return fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {
+    ...init,
+    headers,
+  });
+}
+
+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";
+}