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

package/src/cli/index.ts

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 
 import { createProject } from "../create-project";
 import { buildAgentCapsule } from "../runtime/build";
@@ -19,7 +20,7 @@ import {
 } from "../runtime/db-commands";
 import { runEvalsFromCwd } from "../runtime/evals";
 import { findAgentKitDocs } from "../runtime/docs";
-import { listCapsuleEnv, setCapsuleEnv, unsetCapsuleEnv } from "../runtime/env";
+import { listCapsuleEnv, loadCapsuleEnv, setCapsuleEnv, unsetCapsuleEnv } from "../runtime/env";
 import { loadDeployReadinessContext, stableCloudProjectId, type DeployReadinessContext } from "../runtime/deploy-readiness";
 import { runToolFromCwd } from "../runtime/tool-runner";
 import { startAgentDevServer } from "../runtime/dev-server";
@@ -28,13 +29,59 @@ import { AgentKitError, isAgentKitError } from "../runtime/errors";
 import { prepareVpsDeploy } from "../runtime/targets/vps/deploy";
 
 const defaultAgentKitCloudApiUrl = "https://agentkit-cloud.aibuilders.com.br";
+const defaultDeployChatAccessTokenName = "agentkit-chat-ui";
+const defaultDeployChatAccessTokenPath = ".agentkit/chat-access-token.json";
 
 function renderHelp(): string {
   return `AgentKit
 
+Create, run, inspect, and deploy Agent Capsules.
+
+Quick start:
+  agentkit new support-agent --template support
+  cd support-agent
+  npm run dev
+  npm run chat -- --message "hello"
+
+Usage:
+  agentkit <command> [options]
+
+Start:
+  agentkit new <name> [--template blank|support] [--no-install]
+  agentkit dev
+  agentkit chat-ui --deploy
+  agentkit chat --message <text>
+  agentkit inspect
+
+Build:
+  agentkit tool <name> [--input <path-or-json>]
+  agentkit db migrate
+  agentkit eval run
+  agentkit conversations list
+
+Deploy:
+  agentkit login --token <token>
+  agentkit deploy doctor
+  agentkit secret set <NAME> --stdin
+  agentkit deploy
+  agentkit deploy status
+
+More:
+  agentkit channels ...
+  agentkit access token ...
+  agentkit env ...
+  agentkit docs full
+  agentkit help commands
+`;
+}
+
+function renderCommandReference(): string {
+  return `AgentKit Command Reference
+
 Usage:
-  agentkit new <name> [--template blank|support]
+  agentkit new <name> [--template blank|support] [--no-install]
   agentkit dev
+  agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
   agentkit chat --message <text>
   agentkit tool <name> [--input <path-or-json>]
   agentkit db migrate
@@ -61,23 +108,30 @@ Usage:
   agentkit deploy pause [--api <url>]
   agentkit deploy resume [--api <url>]
   agentkit secret set <NAME> <VALUE> [--api <url>]
+  agentkit secret set <NAME> --stdin [--api <url>]
+  agentkit secret set <NAME> --from-env [ENV_NAME] [--api <url>]
+  agentkit secret set <NAME> --from-local-env [--api <url>]
   agentkit secret list [--api <url>]
   agentkit secret unset <NAME> [--api <url>]
-  agentkit access token create <name> [--api <url>]
+  agentkit access token create <name> [--api <url>] [--out <path>]
   agentkit access token list [--api <url>]
   agentkit access token revoke <token-id> [--api <url>]
   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 help commands
   agentkit --help
 
 Commands:
   new             Create a new Agent Capsule
   dev             Run the Agent Capsule locally
+  chat-ui         Run a local chat UI, optionally pointed at a hosted deploy
   chat            Send one message to the local Agent Capsule
   tool            Run one registered tool directly
   db              Manage the local SQLite database
@@ -94,6 +148,7 @@ Commands:
   env             Manage local .env values without opening code
   docs            Print AgentKit docs locations
   handoff         Print a ready-to-paste prompt for another coding agent
+  help            Print focused help or the full command reference
 
 Examples:
   agentkit new support-agent --template support
@@ -145,34 +200,60 @@ async function main() {
     return;
   }
 
+  if (args.command === "help") {
+    const [topic] = args.positional;
+
+    if (!topic) {
+      console.log(renderHelp());
+      return;
+    }
+
+    if (topic === "commands") {
+      console.log(renderCommandReference());
+      return;
+    }
+
+    throw new Error("Usage: agentkit help [commands]");
+  }
+
   if (args.command === "new") {
     const [name] = args.positional;
     const template = String(args.flags.template ?? "blank");
+    const shouldInstall = args.flags["no-install"] !== true;
 
     if (!name) {
-      throw new Error("Missing project name. Usage: agentkit new <name> [--template blank|support]");
+      throw new Error("Missing project name. Usage: agentkit new <name> [--template blank|support] [--no-install]");
     }
 
     const result = await createProject({ name, template, cwd: process.cwd() });
     console.log(`Created ${result.name} at ${result.path}`);
+
+    if (shouldInstall) {
+      console.log("");
+      console.log("Installing dependencies...");
+      await installProjectDependencies(result.path);
+    }
+
     console.log("");
     console.log("Next:");
     if (resolve(result.path) !== resolve(process.cwd())) {
       console.log(`  cd ${result.name}`);
     }
-    console.log("  npm install");
+    if (!shouldInstall) {
+      console.log("  npm install");
+    }
     console.log("  open this folder in Codex or Claude Code");
     console.log('  ask: "Develop an appointment and intake agent for an ophthalmology office"');
     console.log('  npm run chat -- --message "hello"');
     console.log("  npm run dev");
     console.log("  npm run agentkit -- deploy");
     console.log("");
-    console.log("Optional: manage local secrets with `npm run agentkit -- env set <NAME> <VALUE>`.");
+    console.log("Optional: manage local secrets with `printf %s \"$VALUE\" | npm run agentkit -- env set <NAME> --stdin`.");
     return;
   }
 
   if (args.command === "dev") {
-    const port = parsePort(args.flags.port);
+    const port = parsePort(args.flags.port, "agentkit dev --port <number>");
     const devServer = await startAgentDevServer(process.cwd(), { port });
 
     console.log("Agent Capsule running");
@@ -185,6 +266,28 @@ async function main() {
     return;
   }
 
+  if (args.command === "chat-ui") {
+    if (!args.flags.deploy) {
+      throw new Error("Usage: agentkit chat-ui --deploy [--port <number>] [--token-file <path>]");
+    }
+
+    const port = parsePort(args.flags.port, "agentkit chat-ui --deploy --port <number>") ?? 4124;
+    const tokenFile = parseOptionalStringFlag(
+      args.flags["token-file"],
+      "token-file",
+      "agentkit chat-ui --deploy --token-file <path>",
+    );
+    const server = await startDeployChatUiServer(process.cwd(), { port, tokenFile });
+
+    console.log("AgentKit hosted chat UI running");
+    console.log("");
+    console.log(`Chat:       ${server.url}`);
+    console.log(`Production: ${server.deployUrl}`);
+    console.log(`Token:      ${server.tokenSource}`);
+    await waitForShutdown(server.stop);
+    return;
+  }
+
   if (args.command === "chat") {
     const message = args.flags.message;
 
@@ -351,8 +454,25 @@ async function main() {
 
   if (args.command === "login") {
     const token = parseRequiredStringFlag(args.flags.token, "token", "agentkit login --token <token> [--api <url>]");
-    await writeCloudAuth({ apiUrl: parseCloudApiUrl(args.flags.api), token });
-    console.log("AgentKit Cloud token stored.");
+    const apiUrl = parseCloudApiUrl(args.flags.api);
+    const verified = await verifyCloudLogin(apiUrl, token);
+    await writeCloudAuth({ apiUrl, token });
+    const email = verified.me.account?.email;
+    console.log(email ? `Logged in to AgentKit Cloud as ${email}.` : "AgentKit Cloud token verified and stored.");
+
+    const hasCloudflareAlpha = (verified.capabilities.capabilities ?? []).some(
+      (capability) => capability.name === "cloudflare_deploy_alpha" && capability.status === "active",
+    );
+    console.log(
+      hasCloudflareAlpha
+        ? "Entitlement: cloudflare_deploy_alpha active."
+        : "Warning: cloudflare_deploy_alpha entitlement was not found for this account.",
+    );
+
+    if (process.env.AGENTKIT_CLOUD_API_TOKEN && process.env.AGENTKIT_CLOUD_API_TOKEN !== token) {
+      console.log("Warning: AGENTKIT_CLOUD_API_TOKEN is set and will override this saved login in the current shell.");
+    }
+
     return;
   }
 
@@ -450,6 +570,12 @@ async function main() {
       anonymous: anonymous || !auth?.token,
     });
     const statePath = await writeLocalDeployState(result.root, deploy);
+    const chatAccess = await ensureDeployChatAccessToken({
+      apiUrl,
+      root: result.root,
+      deployId: deploy.deploy.id,
+      skip: anonymous || !auth?.token || deploy.deploy.access.mode === "public",
+    });
 
     console.log("");
     console.log("Deploy ready");
@@ -457,6 +583,15 @@ async function main() {
     console.log(`Project:   ${deploy.project.id}`);
     console.log(`Deploy:    ${deploy.deploy.id}`);
     console.log(`State:     ${statePath}`);
+
+    if (chatAccess?.status === "ready") {
+      console.log(`Chat auth: ${relativePath(process.cwd(), chatAccess.path)}`);
+    } else if (chatAccess?.status === "skipped") {
+      console.log("Chat auth: public or anonymous deploy; no local chat token was created.");
+    } else if (chatAccess?.status === "failed") {
+      console.log(`Chat auth: could not create local chat token. ${formatReadinessError(chatAccess.error)}`);
+      console.log(`Run:       agentkit access token create ${defaultDeployChatAccessTokenName} --out ${defaultDeployChatAccessTokenPath}`);
+    }
     return;
   }
 
@@ -474,10 +609,18 @@ async function main() {
     }
 
     if (subcommand === "set") {
-      const value = valueParts.join(" ");
+      const value = await resolveSecretInputValue({
+        name,
+        valueParts,
+        stdinFlag: args.flags.stdin,
+        fromEnvFlag: args.flags["from-env"],
+        fromLocalEnvFlag: args.flags["from-local-env"],
+        localEnvRoot: args.flags["from-local-env"] !== undefined ? await findAgentCapsuleRoot(process.cwd()) : undefined,
+        usage: "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 [--api <url>]",
+      });
 
-      if (!name || value.length === 0) {
-        throw new Error("Usage: agentkit secret set <NAME> <VALUE> [--api <url>]");
+      if (!name) {
+        throw new Error("Usage: 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 [--api <url>]");
       }
 
       const payload = await cloudApiRequest(apiUrl, `/v1/projects/${encodeURIComponent(projectId)}/secrets/${encodeURIComponent(name)}`, {
@@ -500,14 +643,14 @@ async function main() {
       return;
     }
 
-    throw new Error("Usage: agentkit secret set <NAME> <VALUE> | agentkit secret list | agentkit secret unset <NAME>");
+    throw new Error("Usage: 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 list | agentkit secret unset <NAME>");
   }
 
   if (args.command === "access") {
     const [subcommand, noun, name] = args.positional;
 
     if (subcommand !== "token") {
-      throw new Error("Usage: agentkit access token create <name> | list | revoke <token-id> [--api <url>]");
+      throw new Error("Usage: agentkit access token create <name> [--out <path>] | list | revoke <token-id> [--api <url>]");
     }
 
     const state = await requireLocalDeployState();
@@ -518,7 +661,7 @@ async function main() {
         method: "POST",
         body: JSON.stringify({ name }),
       });
-      printJson(payload);
+      await printJsonOrWrite(payload, args.flags.out, "agentkit access token create <name> [--api <url>] [--out <path>]");
       return;
     }
 
@@ -540,7 +683,7 @@ async function main() {
       return;
     }
 
-    throw new Error("Usage: agentkit access token create <name> | list | revoke <token-id> [--api <url>]");
+    throw new Error("Usage: agentkit access token create <name> [--out <path>] | list | revoke <token-id> [--api <url>]");
   }
 
   if (args.command === "channels") {
@@ -568,10 +711,17 @@ async function main() {
     }
 
     if (subcommand === "set") {
-      const value = valueParts.join(" ");
+      const value = await resolveSecretInputValue({
+        name,
+        valueParts,
+        stdinFlag: args.flags.stdin,
+        fromEnvFlag: args.flags["from-env"],
+        fromLocalEnvFlag: undefined,
+        usage: "agentkit env set <NAME> <VALUE> | agentkit env set <NAME> --stdin | agentkit env set <NAME> --from-env [ENV_NAME]",
+      });
 
-      if (!name || value.length === 0) {
-        throw new Error("Usage: agentkit env set <NAME> <VALUE>");
+      if (!name) {
+        throw new Error("Usage: agentkit env set <NAME> <VALUE> | agentkit env set <NAME> --stdin | agentkit env set <NAME> --from-env [ENV_NAME]");
       }
 
       await setCapsuleEnv(root, name, value);
@@ -589,7 +739,7 @@ async function main() {
       return;
     }
 
-    throw new Error("Usage: agentkit env list | agentkit env set <NAME> <VALUE> | agentkit env unset <NAME>");
+    throw new Error("Usage: agentkit env list | agentkit env set <NAME> <VALUE> | agentkit env set <NAME> --stdin | agentkit env set <NAME> --from-env [ENV_NAME] | agentkit env unset <NAME>");
   }
 
   if (args.command === "docs") {
@@ -666,7 +816,6 @@ Verification:
 Run these before you finish:
 
 \`\`\`sh
-npm install
 npm run typecheck
 npm run agentkit -- inspect
 npm run chat -- --message "hello"
@@ -716,6 +865,36 @@ type CloudCapabilitiesResponse = {
   }>;
 };
 
+type CloudLimitsResponse = {
+  online_agents?: {
+    account?: {
+      used?: number | null;
+      limit?: number | null;
+    };
+    global?: {
+      used?: number | null;
+      limit?: number | null;
+    };
+  };
+};
+
+type DeployAccessTokenCreateResponse = {
+  access_token?: {
+    id?: string;
+    deploy_id?: string;
+    name?: string;
+    token?: string;
+  };
+};
+
+type DeployAccessTokenListResponse = {
+  access_tokens?: Array<{
+    id?: string;
+    deploy_id?: string;
+    name?: string;
+  }>;
+};
+
 type CloudSecretsResponse = {
   secrets?: Array<{
     name?: string;
@@ -771,7 +950,7 @@ async function checkDeployReadiness(options: {
       checks.push({
         status: "fail",
         title: "Login",
-        message: `AgentKit Cloud rejected the stored token. ${formatReadinessError(error)}`,
+        message: `AgentKit Cloud rejected the token from ${formatCloudAuthSource(auth)}. ${formatReadinessError(error)}`,
         action: "agentkit login --token <token>",
       });
     }
@@ -802,6 +981,58 @@ async function checkDeployReadiness(options: {
         message: `Could not verify AgentKit Cloud capabilities. ${formatReadinessError(error)}`,
       });
     }
+
+    try {
+      const payload = (await cloudApiRequest(options.apiUrl, "/v1/me/limits", {
+        method: "GET",
+      })) as CloudLimitsResponse;
+      const account = payload.online_agents?.account;
+      const global = payload.online_agents?.global;
+      const accountLimit = normalizeOptionalNumber(account?.limit);
+      const accountUsed = normalizeOptionalNumber(account?.used);
+      const globalLimit = normalizeOptionalNumber(global?.limit);
+      const globalUsed = normalizeOptionalNumber(global?.used);
+
+      if (accountLimit !== undefined && accountUsed !== undefined && accountUsed >= accountLimit) {
+        checks.push({
+          status: "fail",
+          title: "Online agent capacity",
+          message: `This account is already using ${accountUsed}/${accountLimit} online AgentKit deploys.`,
+          action: "agentkit deploy pause",
+        });
+      } else if (globalLimit !== undefined && globalUsed !== undefined && globalUsed >= globalLimit) {
+        checks.push({
+          status: "fail",
+          title: "Online agent capacity",
+          message: `AgentKit Cloud is already using ${globalUsed}/${globalLimit} global online deploy slots.`,
+          action: "agentkit deploy status",
+        });
+      } else if (accountLimit !== undefined && accountUsed !== undefined) {
+        checks.push({
+          status: "pass",
+          title: "Online agent capacity",
+          message: `Account has capacity: ${accountUsed}/${accountLimit} online deploys are in use.`,
+        });
+      } else if (globalLimit !== undefined && globalUsed !== undefined) {
+        checks.push({
+          status: "pass",
+          title: "Online agent capacity",
+          message: `Global capacity is available: ${globalUsed}/${globalLimit} online deploys are in use.`,
+        });
+      } else {
+        checks.push({
+          status: "info",
+          title: "Online agent capacity",
+          message: "No online deploy limit is configured for this account.",
+        });
+      }
+    } catch (error) {
+      checks.push({
+        status: "warn",
+        title: "Online agent capacity",
+        message: `Could not verify online deploy capacity. ${formatReadinessError(error)}`,
+      });
+    }
   }
 
   if (context.agentKitManagedSecrets.length > 0) {
@@ -901,14 +1132,18 @@ function printDeployReadinessReport(report: DeployReadinessReport): void {
 
 function secretSetCommand(secret: string, source: DeployReadinessContext["localSecrets"][string] | undefined): string {
   if (source?.dotenv) {
-    return `agentkit secret set ${secret} <value-from-.env>`;
+    return `agentkit secret set ${secret} --from-local-env`;
   }
 
   if (source?.environment) {
-    return `agentkit secret set ${secret} "$${secret}"`;
+    return `agentkit secret set ${secret} --from-env`;
   }
 
-  return `agentkit secret set ${secret} <value>`;
+  return `agentkit secret set ${secret} --stdin`;
+}
+
+function normalizeOptionalNumber(value: number | null | undefined): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
 function formatReadinessError(error: unknown): string {
@@ -1379,6 +1614,7 @@ function cloudFetch(apiUrl: string, path: string, init: RequestInit = {}): Promi
 type CloudAuthConfig = {
   apiUrl: string;
   token: string;
+  source?: "environment" | "file";
 };
 
 function cloudAuthPath(): string {
@@ -1390,6 +1626,7 @@ async function readCloudAuth(): Promise<CloudAuthConfig | null> {
     return {
       apiUrl: process.env.AGENTKIT_CLOUD_API_URL ?? defaultAgentKitCloudApiUrl,
       token: process.env.AGENTKIT_CLOUD_API_TOKEN,
+      source: "environment",
     };
   }
 
@@ -1400,6 +1637,7 @@ async function readCloudAuth(): Promise<CloudAuthConfig | null> {
       return {
         apiUrl: typeof parsed.apiUrl === "string" ? parsed.apiUrl : defaultAgentKitCloudApiUrl,
         token: parsed.token,
+        source: "file",
       };
     }
   } catch {
@@ -1414,6 +1652,87 @@ async function writeCloudAuth(config: CloudAuthConfig): Promise<void> {
   await writeFile(cloudAuthPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
 }
 
+async function ensureDeployChatAccessToken(options: {
+  apiUrl: string;
+  root: string;
+  deployId: string;
+  skip: boolean;
+}): Promise<
+  | { status: "ready"; path: string; tokenId: string; created: boolean }
+  | { status: "skipped" }
+  | { status: "failed"; error: unknown }
+> {
+  if (options.skip) {
+    return { status: "skipped" };
+  }
+
+  try {
+    const path = join(options.root, defaultDeployChatAccessTokenPath);
+    const existing = await readDeployAccessTokenFile(path);
+
+    if (existing?.deploy_id === options.deployId && existing.id) {
+      const listed = (await cloudApiRequest(
+        options.apiUrl,
+        `/v1/deploys/${encodeURIComponent(options.deployId)}/access-tokens`,
+        { method: "GET" },
+      )) as DeployAccessTokenListResponse;
+      const stillExists = (listed.access_tokens ?? []).some((token) => token.id === existing.id);
+
+      if (stillExists) {
+        return { status: "ready", path, tokenId: existing.id, created: false };
+      }
+    }
+
+    const created = (await cloudApiRequest(
+      options.apiUrl,
+      `/v1/deploys/${encodeURIComponent(options.deployId)}/access-tokens`,
+      {
+        method: "POST",
+        body: JSON.stringify({ name: defaultDeployChatAccessTokenName }),
+      },
+    )) as DeployAccessTokenCreateResponse;
+    const token = created.access_token;
+
+    if (!token?.id || token.deploy_id !== options.deployId || !token.token) {
+      throw new AgentKitError("access_token_invalid", "AgentKit Cloud returned an invalid deploy access token payload.");
+    }
+
+    await writeSecretJson(path, created);
+    return { status: "ready", path, tokenId: token.id, created: true };
+  } catch (error) {
+    return { status: "failed", error };
+  }
+}
+
+async function readDeployAccessTokenFile(path: string): Promise<{ id?: string; deploy_id?: string } | null> {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8")) as DeployAccessTokenCreateResponse;
+    return parsed.access_token ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeSecretJson(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+
+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 };
+}
+
 async function clearCloudAuth(): Promise<void> {
   await rm(cloudAuthPath(), { force: true });
 }
@@ -1472,16 +1791,66 @@ async function cloudApiRequest(apiUrl: string, path: string, init: RequestInit):
       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));
+    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;
 }
 
+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;
+}
+
 function printJson(value: unknown): void {
   console.log(JSON.stringify(value, null, 2));
 }
 
+async function printJsonOrWrite(value: unknown, outFlag: string | boolean | undefined, usage: string): Promise<void> {
+  const outPath = parseOptionalStringFlag(outFlag, "out", usage);
+
+  if (!outPath) {
+    printJson(value);
+    return;
+  }
+
+  const absolutePath = resolve(process.cwd(), outPath);
+  await writeSecretJson(absolutePath, value);
+  console.log(`Deploy access token written to ${absolutePath}`);
+}
+
 function readCloudError(payload: unknown, status: number): string {
   if (payload && typeof payload === "object" && "error" in payload) {
     const error = (payload as { error?: { message?: unknown } }).error;
@@ -1493,19 +1862,36 @@ function readCloudError(payload: unknown, status: number): string {
   return `AgentKit Cloud request failed with HTTP ${status}.`;
 }
 
-function parsePort(value: string | boolean | undefined): number | undefined {
+function formatCloudAuthSource(auth: CloudAuthConfig): string {
+  if (auth.source === "environment") {
+    return "AGENTKIT_CLOUD_API_TOKEN";
+  }
+
+  if (auth.source === "file") {
+    return cloudAuthPath();
+  }
+
+  return "AgentKit Cloud auth";
+}
+
+function relativePath(root: string, path: string): string {
+  const output = relative(root, path);
+  return output.startsWith("..") ? path : output || ".";
+}
+
+function parsePort(value: string | boolean | undefined, usage = "agentkit dev --port <number>"): number | undefined {
   if (value === undefined) {
     return undefined;
   }
 
   if (typeof value !== "string") {
-    throw new Error("Missing port. Usage: agentkit dev --port <number>");
+    throw new Error(`Missing port. Usage: ${usage}`);
   }
 
   const port = Number(value);
 
   if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    throw new Error("Invalid port. Usage: agentkit dev --port <number>");
+    throw new Error(`Invalid port. Usage: ${usage}`);
   }
 
   return port;
@@ -1557,6 +1943,90 @@ function parseOptionalStringFlag(value: string | boolean | undefined, name: stri
   return value.trim();
 }
 
+async function resolveSecretInputValue(options: {
+  name: string | undefined;
+  valueParts: string[];
+  stdinFlag: string | boolean | undefined;
+  fromEnvFlag: string | boolean | undefined;
+  fromLocalEnvFlag: string | boolean | undefined;
+  localEnvRoot?: string;
+  usage: string;
+}): Promise<string> {
+  const { name, valueParts, stdinFlag, fromEnvFlag, fromLocalEnvFlag, localEnvRoot, usage } = options;
+
+  if (!name) {
+    throw new Error(`Missing name. Usage: ${usage}`);
+  }
+
+  const hasInlineValue = valueParts.length > 0;
+  const hasStdin = stdinFlag !== undefined;
+  const hasFromEnv = fromEnvFlag !== undefined;
+  const hasFromLocalEnv = fromLocalEnvFlag !== undefined;
+  const inputModes = [hasInlineValue, hasStdin, hasFromEnv, hasFromLocalEnv].filter(Boolean).length;
+
+  if (inputModes !== 1) {
+    throw new Error(`Provide exactly one value source. Usage: ${usage}`);
+  }
+
+  let value: string;
+
+  if (hasInlineValue) {
+    value = valueParts.join(" ");
+  } else if (hasStdin) {
+    if (stdinFlag !== true) {
+      throw new Error(`--stdin does not take a value. Usage: ${usage}`);
+    }
+
+    value = stripOneTrailingNewline(await readStdinText());
+  } else if (hasFromEnv) {
+    const envName = fromEnvFlag === true ? name : parseRequiredStringFlag(fromEnvFlag, "env name", usage);
+    const envValue = process.env[envName];
+
+    if (envValue === undefined) {
+      throw new AgentKitError("secret_not_found", `Environment variable ${envName} is not set.`);
+    }
+
+    value = envValue;
+  } else {
+    if (fromLocalEnvFlag !== true) {
+      throw new Error(`--from-local-env does not take a value. Usage: ${usage}`);
+    }
+
+    if (!localEnvRoot) {
+      throw new Error(`--from-local-env is not available for this command. Usage: ${usage}`);
+    }
+
+    const localEnv = await loadCapsuleEnv(localEnvRoot, {});
+    const localValue = localEnv[name];
+
+    if (localValue === undefined) {
+      throw new AgentKitError("secret_not_found", `Local .env does not contain ${name}.`);
+    }
+
+    value = localValue;
+  }
+
+  if (value.length === 0) {
+    throw new Error(`Secret value cannot be empty. Usage: ${usage}`);
+  }
+
+  return value;
+}
+
+async function readStdinText(): Promise<string> {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function stripOneTrailingNewline(value: string): string {
+  return value.replace(/\r?\n$/, "");
+}
+
 function printBuildResult(result: Awaited<ReturnType<typeof buildAgentCapsule>>): void {
   console.log("AgentKit build complete");
   console.log("");
@@ -1614,6 +2084,14 @@ async function deployCloudflare(wranglerPath: string, buildDir: string): Promise
   }
 }
 
+async function installProjectDependencies(projectPath: string): Promise<void> {
+  const exitCode = await runInheritedCommand("npm", ["install"], projectPath);
+
+  if (exitCode !== 0) {
+    throw new Error(`Dependency install failed with exit code ${exitCode}. Run \`npm install\` in ${projectPath}.`);
+  }
+}
+
 function runInheritedCommand(command: string, args: string[], cwd: string): Promise<number> {
   return new Promise((resolvePromise, reject) => {
     const child = spawn(command, args, {
@@ -1669,6 +2147,378 @@ function parseJsonInput(source: string, label: string): unknown {
   }
 }
 
+async function startDeployChatUiServer(
+  cwd: string,
+  options: { port: number; tokenFile?: string },
+): Promise<{ url: string; deployUrl: string; tokenSource: string; stop(): Promise<void> }> {
+  const root = await findAgentCapsuleRoot(cwd);
+  const state = await readLocalDeployStateIfExists(root);
+
+  if (!state?.url) {
+    throw new Error("No hosted deploy URL found. Run agentkit deploy first.");
+  }
+
+  const tokenPath = options.tokenFile
+    ? resolve(root, options.tokenFile)
+    : join(root, defaultDeployChatAccessTokenPath);
+  const hostname = "localhost";
+  const deployUrl = state.url;
+  const server = createServer(async (request, response) => {
+    try {
+      const requestUrl = new URL(request.url ?? "/", `http://${request.headers.host ?? `${hostname}:${options.port}`}`);
+
+      if (request.method === "GET" && requestUrl.pathname === "/") {
+        sendHtml(response, renderDeployChatUi({ deployUrl }));
+        return;
+      }
+
+      if (request.method === "GET" && requestUrl.pathname === "/health") {
+        sendJson(response, 200, { status: "ok", target: "deploy-chat-ui", deployUrl });
+        return;
+      }
+
+      if (request.method === "GET" && requestUrl.pathname === "/_agentkit") {
+        sendJson(response, 200, {
+          deployUrl,
+          access: "proxied",
+          tokenSource: process.env.AGENTKIT_DEPLOY_ACCESS_TOKEN ? "AGENTKIT_DEPLOY_ACCESS_TOKEN" : relativePath(root, tokenPath),
+        });
+        return;
+      }
+
+      if (request.method === "POST" && (requestUrl.pathname === "/v1/chat" || requestUrl.pathname === "/chat")) {
+        const token = await readDeployAccessTokenForUi(tokenPath);
+        const body = await readIncomingBody(request);
+        const contentTypeHeader = request.headers["content-type"];
+        const contentType = Array.isArray(contentTypeHeader)
+          ? contentTypeHeader[0] ?? "application/json"
+          : contentTypeHeader ?? "application/json";
+        const upstream = await fetch(new URL("/v1/chat", deployUrl).href, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${token}`,
+            "Content-Type": contentType,
+          },
+          body,
+        });
+        const text = await upstream.text();
+
+        response.writeHead(upstream.status, {
+          "content-type": upstream.headers.get("content-type") ?? "application/json",
+        });
+        response.end(text);
+        return;
+      }
+
+      sendJson(response, 404, { error: { code: "not_found", message: "Route not found." } });
+    } catch (error) {
+      sendJson(response, 500, {
+        error: {
+          code: isAgentKitError(error) ? error.code : "deploy_chat_ui_error",
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  });
+
+  await new Promise<void>((resolvePromise, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, hostname, () => {
+      server.off("error", reject);
+      resolvePromise();
+    });
+  });
+
+  return {
+    url: `http://${hostname}:${options.port}`,
+    deployUrl,
+    tokenSource: process.env.AGENTKIT_DEPLOY_ACCESS_TOKEN ? "AGENTKIT_DEPLOY_ACCESS_TOKEN" : relativePath(root, tokenPath),
+    stop: () =>
+      new Promise<void>((resolvePromise, reject) => {
+        server.close((error) => (error ? reject(error) : resolvePromise()));
+      }),
+  };
+}
+
+async function readDeployAccessTokenForUi(tokenPath: string): Promise<string> {
+  if (process.env.AGENTKIT_DEPLOY_ACCESS_TOKEN) {
+    return process.env.AGENTKIT_DEPLOY_ACCESS_TOKEN;
+  }
+
+  let payload: unknown;
+
+  try {
+    payload = JSON.parse(await readFile(tokenPath, "utf8"));
+  } catch (error) {
+    throw new AgentKitError(
+      "deploy_access_token_missing",
+      `Could not read a clean deploy access token file at ${tokenPath}. Run: agentkit access token create ${defaultDeployChatAccessTokenName} --out ${defaultDeployChatAccessTokenPath}`,
+    );
+  }
+
+  const token =
+    payload && typeof payload === "object"
+      ? (payload as { access_token?: { token?: unknown }; token?: unknown; accessToken?: unknown }).access_token?.token ??
+        (payload as { token?: unknown }).token ??
+        (payload as { accessToken?: unknown }).accessToken
+      : undefined;
+
+  if (typeof token !== "string" || token.trim().length === 0) {
+    throw new AgentKitError(
+      "deploy_access_token_invalid",
+      `Deploy access token file ${tokenPath} does not contain access_token.token. Recreate it with: agentkit access token create ${defaultDeployChatAccessTokenName} --out ${defaultDeployChatAccessTokenPath}`,
+    );
+  }
+
+  return token.trim();
+}
+
+function readIncomingBody(request: IncomingMessage): Promise<string> {
+  return new Promise((resolvePromise, reject) => {
+    let body = "";
+    request.setEncoding("utf8");
+    request.on("data", (chunk) => {
+      body += chunk;
+    });
+    request.on("end", () => resolvePromise(body));
+    request.on("error", reject);
+  });
+}
+
+function sendJson(response: ServerResponse, status: number, body: unknown): void {
+  response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify(body, null, 2));
+}
+
+function sendHtml(response: ServerResponse, body: string): void {
+  response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+  response.end(body);
+}
+
+function renderDeployChatUi(input: { deployUrl: string }): string {
+  const deployUrl = escapeHtml(input.deployUrl);
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>AgentKit Hosted Chat</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: #f6f7f5;
+        --panel: #ffffff;
+        --ink: #182022;
+        --muted: #667175;
+        --line: #d9ded9;
+        --accent: #176b5d;
+        --danger: #9f2d2d;
+      }
+
+      * { box-sizing: border-box; }
+
+      body {
+        margin: 0;
+        min-height: 100svh;
+        background: var(--bg);
+        color: var(--ink);
+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      }
+
+      main {
+        min-height: 100svh;
+        display: grid;
+        grid-template-rows: auto 1fr auto;
+        background: var(--panel);
+      }
+
+      header {
+        border-bottom: 1px solid var(--line);
+        padding: 18px 22px;
+      }
+
+      h1 {
+        margin: 0 0 4px;
+        font-size: 20px;
+        line-height: 1.2;
+      }
+
+      code {
+        color: var(--muted);
+        font-size: 12px;
+        overflow-wrap: anywhere;
+      }
+
+      #messages {
+        padding: 22px;
+        overflow: auto;
+        display: flex;
+        flex-direction: column;
+        gap: 12px;
+      }
+
+      .message {
+        max-width: 780px;
+        display: grid;
+        gap: 4px;
+      }
+
+      .message.user {
+        align-self: end;
+      }
+
+      .role {
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+        text-transform: uppercase;
+      }
+
+      .bubble {
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        padding: 12px 14px;
+        white-space: pre-wrap;
+        line-height: 1.45;
+        background: #fbfbfa;
+      }
+
+      .user .bubble {
+        border-color: #b8d8ce;
+        background: #e8f5f0;
+      }
+
+      .error .bubble {
+        border-color: #e1b1b1;
+        color: var(--danger);
+        background: #fff6f6;
+      }
+
+      form {
+        border-top: 1px solid var(--line);
+        padding: 14px;
+        display: grid;
+        grid-template-columns: 1fr auto;
+        gap: 10px;
+      }
+
+      textarea {
+        min-height: 52px;
+        max-height: 180px;
+        resize: vertical;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        padding: 12px;
+        color: var(--ink);
+        font: inherit;
+      }
+
+      button {
+        min-width: 96px;
+        border: 0;
+        border-radius: 8px;
+        padding: 0 18px;
+        color: white;
+        background: var(--accent);
+        font: inherit;
+        font-weight: 700;
+        cursor: pointer;
+      }
+
+      button:disabled {
+        cursor: wait;
+        opacity: 0.65;
+      }
+
+      @media (max-width: 640px) {
+        form {
+          grid-template-columns: 1fr;
+        }
+
+        button {
+          min-height: 44px;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>AgentKit Hosted Chat</h1>
+        <code>${deployUrl}</code>
+      </header>
+      <section id="messages" aria-live="polite"></section>
+      <form id="form">
+        <textarea id="message" name="message" placeholder="Type a message" required autofocus></textarea>
+        <button id="send" type="submit">Send</button>
+      </form>
+    </main>
+    <script>
+      const form = document.querySelector("#form");
+      const textarea = document.querySelector("#message");
+      const send = document.querySelector("#send");
+      const messages = document.querySelector("#messages");
+      let conversationId = null;
+
+      function addMessage(role, content, className = "") {
+        const wrapper = document.createElement("article");
+        wrapper.className = ["message", role, className].filter(Boolean).join(" ");
+        const label = document.createElement("div");
+        label.className = "role";
+        label.textContent = role;
+        const bubble = document.createElement("div");
+        bubble.className = "bubble";
+        bubble.textContent = content;
+        wrapper.append(label, bubble);
+        messages.append(wrapper);
+        messages.scrollTop = messages.scrollHeight;
+      }
+
+      form.addEventListener("submit", async (event) => {
+        event.preventDefault();
+        const message = textarea.value.trim();
+        if (!message) return;
+
+        addMessage("user", message);
+        textarea.value = "";
+        send.disabled = true;
+
+        try {
+          const response = await fetch("/v1/chat", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ message, conversationId }),
+          });
+          const payload = await response.json();
+
+          if (!response.ok) {
+            throw new Error(payload.error?.message || "Request failed");
+          }
+
+          conversationId = payload.conversationId || conversationId;
+          addMessage("assistant", payload.message?.content || "");
+        } catch (error) {
+          addMessage("error", error instanceof Error ? error.message : String(error), "error");
+        } finally {
+          send.disabled = false;
+          textarea.focus();
+        }
+      });
+    </script>
+  </body>
+</html>`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
 async function waitForShutdown(stop: () => Promise<void>): Promise<void> {
   await new Promise<void>((resolve) => {
     let stopped = false;