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

package/src/cli/index.ts

@@ -1,14 +1,12 @@
 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 { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 
 import { createProject } from "../create-project";
 import { buildAgentCapsule } from "../runtime/build";
 import { findAgentCapsuleRoot, loadAgentCapsule } from "../runtime/config";
 import { readLocalDeployStateIfExists, type LocalDeployState } from "../runtime/core/deploy-state";
-import { listTargetsWithCapability, resolveBuildTarget, resolveDeployTarget } from "../runtime/core/targets";
+import { resolveBuildTarget, resolveDeployTarget } from "../runtime/core/targets";
 import { getConversationFromCwd, listConversationsFromCwd } from "../runtime/conversations";
 import { runAgentMessageFromCwd } from "../runtime/chat";
 import { deployBuildToAgentKitCloud, writeLocalDeployState } from "../runtime/deploy";
@@ -20,177 +18,49 @@ import {
 } from "../runtime/db-commands";
 import { runEvalsFromCwd } from "../runtime/evals";
 import { findAgentKitDocs } from "../runtime/docs";
-import { listCapsuleEnv, loadCapsuleEnv, setCapsuleEnv, unsetCapsuleEnv } from "../runtime/env";
-import { loadDeployReadinessContext, stableCloudProjectId, type DeployReadinessContext } from "../runtime/deploy-readiness";
+import { listCapsuleEnv, setCapsuleEnv, unsetCapsuleEnv } from "../runtime/env";
 import { runToolFromCwd } from "../runtime/tool-runner";
 import { startAgentDevServer } from "../runtime/dev-server";
 import { inspectAgentCapsule } from "../runtime/inspect";
 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] [--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
-  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|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 build [--target cloudflare]
-  agentkit login --token <token> [--api <url>]
-  agentkit logout
-  agentkit deploy [--target cloudflare|vps] [--host <host>] [--api <url>] [--dry-run] [--anonymous] [--local-wrangler]
-  agentkit deploy doctor [--api <url>] [--anonymous]
-  agentkit deploy status [--api <url>]
-  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>] [--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
-  eval            Run local eval files
-  conversations   List and inspect stored local conversations
-  channels        Manage hosted channel resources
-  inspect         Print machine-readable Agent Capsule state
-  build           Build a hosted deploy artifact
-  login           Store an AgentKit Cloud alpha token outside the capsule
-  logout          Remove the stored AgentKit Cloud alpha token
-  deploy          Build and send a hosted artifact to AgentKit Cloud
-  secret          Manage hosted AgentKit Cloud secrets without readback
-  access          Manage hosted deploy access tokens
-  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
-  cd support-agent
-  agentkit dev
-  agentkit tool lookup_order --input '{"orderId":"A100"}'
-  agentkit eval run
-`;
-}
-
-type ParsedArgs = {
-  command?: string;
-  positional: string[];
-  flags: Record<string, string | boolean>;
-};
-
-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 };
-}
+import { parseArgs, isHelpRequested, type ParsedArgs } from "./args";
+import {
+  defaultAgentKitDevPort,
+  defaultDeployChatAccessTokenName,
+  defaultDeployChatAccessTokenPath,
+} from "./constants";
+import {
+  clearCloudAuth,
+  cloudApiRequest,
+  readCloudAuth,
+  readCloudError,
+  resolveCloudApiUrl,
+  verifyCloudLogin,
+  writeCloudAuth,
+  type CloudMeResponse,
+  type DeployAccessTokenCreateResponse,
+  type DeployAccessTokenListResponse,
+} from "./cloud-client";
+import {
+  checkDeployReadiness,
+  formatReadinessError,
+  printDeployReadinessReport,
+  resolveProjectIdForSecretCommand,
+  syncHostedSecretsFromLocal,
+} from "./deploy-readiness";
+import { readDeployAccessTokenForUi, startDeployChatUiServer } from "./deploy-chat-ui";
+import {
+  parseCloudApiUrl,
+  parseOptionalStringFlag,
+  parsePort,
+  parseRequiredStringFlag,
+  parseTargetFlag,
+  resolveSecretInputValue,
+} from "./flags";
+import { renderCommandHelp, renderCommandReference, renderHelp } from "./help";
+import { runInheritedCommand, waitForShutdown } from "./process";
+import { handleChannelsCommand } from "./commands/channels";
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
@@ -200,6 +70,11 @@ async function main() {
     return;
   }
 
+  if (isHelpRequested(args)) {
+    console.log(renderCommandHelp(args.command));
+    return;
+  }
+
   if (args.command === "help") {
     const [topic] = args.positional;
 
@@ -222,7 +97,7 @@ async function main() {
     const shouldInstall = args.flags["no-install"] !== true;
 
     if (!name) {
-      throw new Error("Missing project name. Usage: agentkit new <name> [--template blank|support] [--no-install]");
+      throw new Error("Missing project name. Usage: agentkit new <name> [--template blank|support|dentista] [--no-install]");
     }
 
     const result = await createProject({ name, template, cwd: process.cwd() });
@@ -254,10 +129,17 @@ async function main() {
 
   if (args.command === "dev") {
     const port = parsePort(args.flags.port, "agentkit dev --port <number>");
-    const devServer = await startAgentDevServer(process.cwd(), { port });
+    const devServer = await startAgentDevServer(process.cwd(), { port, basePort: localDevBasePort() });
 
     console.log("Agent Capsule running");
     console.log("");
+    if (devServer.portConflict) {
+      const owner = devServer.portConflict.agent ? ` by ${devServer.portConflict.agent}` : "";
+      console.log(
+        `Port ${devServer.portConflict.port} is already used${owner}. Started ${devServer.capsule.config.name} at ${devServer.urls.chat}.`,
+      );
+      console.log("");
+    }
     console.log(`Chat:      ${devServer.urls.chat}`);
     console.log(`API:       ${devServer.urls.api}`);
     console.log(`Inspect:   ${devServer.urls.inspect}`);
@@ -266,6 +148,20 @@ async function main() {
     return;
   }
 
+  if (args.command === "open") {
+    const server = await findRunningLocalDevServer(process.cwd());
+
+    if (!server) {
+      console.log("No running AgentKit dev server found for this capsule.");
+      console.log("Run: npm run dev");
+      return;
+    }
+
+    await openLocalUrl(server.url);
+    console.log(`Opened ${server.url}`);
+    return;
+  }
+
   if (args.command === "chat-ui") {
     if (!args.flags.deploy) {
       throw new Error("Usage: agentkit chat-ui --deploy [--port <number>] [--token-file <path>]");
@@ -290,12 +186,17 @@ async function main() {
 
   if (args.command === "chat") {
     const message = args.flags.message;
+    const conversationId = parseOptionalStringFlag(
+      args.flags["conversation-id"] ?? args.flags.conversation,
+      "conversation id",
+      'agentkit chat --message "hello" [--conversation-id <id>]',
+    );
 
     if (typeof message !== "string") {
-      throw new Error('Missing message. Usage: agentkit chat --message "hello"');
+      throw new Error('Missing message. Usage: agentkit chat --message "hello" [--conversation-id <id>]');
     }
 
-    const result = await runAgentMessageFromCwd(process.cwd(), { message });
+    const result = await runAgentMessageFromCwd(process.cwd(), { message, conversationId });
     console.log(result.message.content);
     return;
   }
@@ -485,6 +386,20 @@ async function main() {
   if (args.command === "deploy") {
     const [deploySubcommand] = args.positional;
 
+    if (deploySubcommand === "smoke") {
+      const message =
+        parseOptionalStringFlag(args.flags.message ?? args.flags.smoke, "message", 'agentkit deploy smoke --message "hello"') ??
+        "hello";
+      const state = await requireLocalDeployState();
+      const token = await readDeployAccessTokenForSmoke(process.cwd(), state);
+      await runDeploySmoke({
+        deployUrl: requireDeployUrl(state),
+        message,
+        token,
+      });
+      return;
+    }
+
     if (deploySubcommand === "doctor") {
       const report = await checkDeployReadiness({
         apiUrl: await resolveCloudApiUrl(args.flags.api),
@@ -520,6 +435,7 @@ async function main() {
 
     const target = resolveDeployTarget(parseTargetFlag(args.flags.target, "deploy"));
     const anonymous = Boolean(args.flags.anonymous);
+    const smokeMessage = parseOptionalStringFlag(args.flags.smoke, "smoke", 'agentkit deploy --smoke "hello"');
 
     if (target.id === "vps") {
       const host = parseRequiredStringFlag(args.flags.host, "host", "agentkit deploy --target vps --host <host>");
@@ -592,6 +508,24 @@ async function main() {
       console.log(`Chat auth: could not create local chat token. ${formatReadinessError(chatAccess.error)}`);
       console.log(`Run:       agentkit access token create ${defaultDeployChatAccessTokenName} --out ${defaultDeployChatAccessTokenPath}`);
     }
+
+    if (smokeMessage) {
+      if (chatAccess?.status === "failed") {
+        throw new AgentKitError("deploy_smoke_failed", "Could not run deploy smoke because chat access token creation failed.");
+      }
+
+      await runDeploySmoke({
+        deployUrl: requireDeployUrl({
+          deploy_id: deploy.deploy.id,
+          url: deploy.deploy.url,
+        }),
+        message: smokeMessage,
+        token:
+          chatAccess?.status === "ready"
+            ? await readDeployAccessTokenForUi(chatAccess.path)
+            : undefined,
+      });
+    }
     return;
   }
 
@@ -617,6 +551,7 @@ async function main() {
         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>]",
+        inlineSensitiveHelp: "Prefer --stdin, --from-env, or --from-local-env so the value does not enter shell history.",
       });
 
       if (!name) {
@@ -631,6 +566,15 @@ async function main() {
       return;
     }
 
+    if (subcommand === "sync") {
+      if (args.flags["from-local"] !== true) {
+        throw new Error("Usage: agentkit secret sync --from-local [--api <url>]");
+      }
+
+      await syncHostedSecretsFromLocal({ apiUrl, projectId });
+      return;
+    }
+
     if (subcommand === "unset") {
       if (!name) {
         throw new Error("Usage: agentkit secret unset <NAME> [--api <url>]");
@@ -643,7 +587,7 @@ async function main() {
       return;
     }
 
-    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>");
+    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 sync --from-local | agentkit secret list | agentkit secret unset <NAME>");
   }
 
   if (args.command === "access") {
@@ -718,6 +662,7 @@ async function main() {
         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]",
+        inlineSensitiveHelp: "Prefer --stdin or --from-env so the value does not enter shell history.",
       });
 
       if (!name) {
@@ -803,9 +748,12 @@ Rules:
 - Follow the AgentKit contract in llms-full.txt.
 - Treat the owner's request as the brief.
 - Build or update the agent inside this capsule as far as you can without asking for obvious restatements.
+- Do not wait for a wizard or recipe; implement directly in the capsule files.
 - Edit agent behavior in prompts/instructions.md.
 - Edit the agent contract in agentkit.config.ts.
 - Add TypeScript tools under tools/.
+- Keep the first useful version runnable with test/fake unless the owner has already chosen a real provider.
+- Before testing real conversation behavior, ask the owner to choose OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
 - Keep local secrets in .env only.
 - Do not commit or print secret values.
 - Do not edit .agentkit/ directly.
@@ -827,1212 +775,187 @@ If you add a tool, also run a tool smoke test with the fake provider, for exampl
 npm run agentkit -- tool tool_name --input '{}'
 \`\`\`
 
+UI testing:
+- 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.
+- If the provider is still \`test/fake\`, say the UI was tested only with the deterministic fake provider.
+
 Final response:
 - Summarize what changed.
 - List files changed.
 - Paste the verification commands and results.
+- State whether testing used \`test/fake\` or a real provider selected by the owner.
 - Call out any missing user details or blocked checks.
 `;
 }
 
-type DeployReadinessStatus = "pass" | "fail" | "warn" | "info";
-
-type DeployReadinessCheck = {
-  status: DeployReadinessStatus;
-  title: string;
-  message: string;
-  action?: string;
-};
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
-type DeployReadinessReport = {
-  ok: boolean;
-  apiUrl: string;
-  context: DeployReadinessContext;
-  checks: DeployReadinessCheck[];
-};
-
-type CloudMeResponse = {
-  account?: {
-    email?: string;
-    status?: string;
-  };
-};
-
-type CloudCapabilitiesResponse = {
-  capabilities?: Array<{
-    name?: string;
-    status?: string;
-  }>;
-};
-
-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;
-    status?: string;
-    updated_at?: string;
-  }>;
-};
-
-async function checkDeployReadiness(options: {
+async function ensureDeployChatAccessToken(options: {
   apiUrl: string;
-  requireLogin: boolean;
-}): Promise<DeployReadinessReport> {
-  const context = await loadDeployReadinessContext(process.cwd(), process.env);
-  const auth = await readCloudAuth();
-  const checks: DeployReadinessCheck[] = [];
-  let cloudAuthUsable = false;
-
-  if (context.runtime !== "edge") {
-    checks.push({
-      status: "fail",
-      title: "Target runtime",
-      message: 'Cloudflare deploy requires runtime: "edge" in agentkit.config.ts.',
-      action: "set runtime: \"edge\" before deploying to AgentKit Cloud",
-    });
-  } else {
-    checks.push({
-      status: "pass",
-      title: "Target runtime",
-      message: "Capsule is configured for edge deploy.",
-    });
-  }
-
-  if (!auth?.token) {
-    checks.push({
-      status: options.requireLogin ? "fail" : "warn",
-      title: "Login",
-      message: options.requireLogin
-        ? "No AgentKit Cloud token was found for hosted production deploy."
-        : "No AgentKit Cloud token was found; deploy will request anonymous mode.",
-      action: "agentkit login --token <token>",
-    });
-  } else {
-    try {
-      const me = (await cloudApiRequest(options.apiUrl, "/v1/me", { method: "GET" })) as CloudMeResponse;
-      const email = me.account?.email;
-      checks.push({
-        status: "pass",
-        title: "Login",
-        message: email ? `Authenticated as ${email}.` : "AgentKit Cloud token is accepted.",
-      });
-      cloudAuthUsable = true;
-    } catch (error) {
-      checks.push({
-        status: "fail",
-        title: "Login",
-        message: `AgentKit Cloud rejected the token from ${formatCloudAuthSource(auth)}. ${formatReadinessError(error)}`,
-        action: "agentkit login --token <token>",
-      });
-    }
-  }
-
-  if (cloudAuthUsable) {
-    try {
-      const payload = (await cloudApiRequest(options.apiUrl, "/v1/me/capabilities", {
-        method: "GET",
-      })) as CloudCapabilitiesResponse;
-      const capabilities = payload.capabilities ?? [];
-      const hasCloudflareAlpha = capabilities.some(
-        (capability) => capability.name === "cloudflare_deploy_alpha" && capability.status === "active",
-      );
-
-      checks.push({
-        status: hasCloudflareAlpha ? "pass" : "fail",
-        title: "Deploy entitlement",
-        message: hasCloudflareAlpha
-          ? "cloudflare_deploy_alpha is active."
-          : "This account is missing the cloudflare_deploy_alpha entitlement.",
-        ...(hasCloudflareAlpha ? {} : { action: "log in with an invited AgentKit Cloud alpha token" }),
-      });
-    } catch (error) {
-      checks.push({
-        status: "fail",
-        title: "Deploy entitlement",
-        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) {
-    checks.push({
-      status: "info",
-      title: "AgentKit-managed secrets",
-      message: `${context.agentKitManagedSecrets.join(", ")} ${
-        context.agentKitManagedSecrets.length === 1 ? "is" : "are"
-      } provisioned by AgentKit Cloud during deploy.`,
-    });
+  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" };
   }
 
-  if (context.accessMode === "private") {
-    checks.push({
-      status: "info",
-      title: "Private access",
-      message: "AGENTKIT_PRIVATE_TOKEN is required at runtime; AgentKit Cloud generates it and saves it in .agentkit/deploy.json.",
-    });
-  }
+  try {
+    const path = join(options.root, defaultDeployChatAccessTokenPath);
+    const existing = await readDeployAccessTokenFile(path);
 
-  if (context.userManagedSecrets.length === 0) {
-    checks.push({
-      status: "pass",
-      title: "Hosted secrets",
-      message: "No user-managed hosted secrets are required by this capsule.",
-    });
-  } else if (!cloudAuthUsable) {
-    checks.push({
-      status: options.requireLogin ? "fail" : "warn",
-      title: "Hosted secrets",
-      message: `Could not check hosted secrets without a valid AgentKit Cloud login. Required: ${context.userManagedSecrets.join(", ")}.`,
-      action: "agentkit secret list",
-    });
-  } else {
-    try {
-      const payload = (await cloudApiRequest(
+    if (existing?.deploy_id === options.deployId && existing.id) {
+      const listed = (await cloudApiRequest(
         options.apiUrl,
-        `/v1/projects/${encodeURIComponent(context.projectId)}/secrets`,
+        `/v1/deploys/${encodeURIComponent(options.deployId)}/access-tokens`,
         { method: "GET" },
-      )) as CloudSecretsResponse;
-      const hostedSecretNames = new Set((payload.secrets ?? []).map((secret) => secret.name).filter(isString));
-      const missing = context.userManagedSecrets.filter((name) => !hostedSecretNames.has(name));
-
-      if (missing.length === 0) {
-        checks.push({
-          status: "pass",
-          title: "Hosted secrets",
-          message: "All user-managed hosted secrets are set.",
-        });
-      } else {
-        for (const secret of missing) {
-          const localSource = context.localSecrets[secret];
-          checks.push({
-            status: "fail",
-            title: `Hosted secret ${secret}`,
-            message: localSource
-              ? `${secret} is present locally but has not been set in AgentKit Cloud.`
-              : `${secret} is required but missing from AgentKit Cloud.`,
-            action: secretSetCommand(secret, localSource),
-          });
-        }
+      )) as DeployAccessTokenListResponse;
+      const stillExists = (listed.access_tokens ?? []).some((token) => token.id === existing.id);
+
+      if (stillExists) {
+        return { status: "ready", path, tokenId: existing.id, created: false };
       }
-    } catch (error) {
-      checks.push({
-        status: "fail",
-        title: "Hosted secrets",
-        message: `Could not list hosted secrets for project ${context.projectId}. ${formatReadinessError(error)}`,
-        action: "agentkit secret list",
-      });
     }
-  }
 
-  return {
-    ok: checks.every((check) => check.status !== "fail"),
-    apiUrl: options.apiUrl,
-    context,
-    checks,
-  };
-}
-
-function printDeployReadinessReport(report: DeployReadinessReport): void {
-  console.log("AgentKit deploy readiness");
-  console.log(`Project: ${report.context.projectName}`);
-  console.log(`Project ID: ${report.context.projectId}`);
-  console.log(`Target: ${report.context.target}`);
-  console.log(`API: ${report.apiUrl}`);
-  console.log("");
-
-  for (const check of report.checks) {
-    console.log(`[${check.status}] ${check.title}: ${check.message}`);
+    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 (check.action) {
-      console.log(`  Run: ${check.action}`);
+    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.");
     }
-  }
-}
-
-function secretSetCommand(secret: string, source: DeployReadinessContext["localSecrets"][string] | undefined): string {
-  if (source?.dotenv) {
-    return `agentkit secret set ${secret} --from-local-env`;
-  }
 
-  if (source?.environment) {
-    return `agentkit secret set ${secret} --from-env`;
+    await writeSecretJson(path, created);
+    return { status: "ready", path, tokenId: token.id, created: true };
+  } catch (error) {
+    return { status: "failed", error };
   }
-
-  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 {
-  if (isAgentKitError(error)) {
-    return `${error.code}: ${error.message}`;
+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;
   }
-
-  return error instanceof Error ? error.message : String(error);
 }
 
-function isString(value: unknown): value is string {
-  return typeof value === "string";
+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 handleChannelsCommand(args: ParsedArgs): Promise<void> {
-  const [subcommand, first, second, third] = args.positional;
-
-  if (subcommand === "list") {
-    const deployState = await readDeployStateIfExists(process.cwd());
-
-    if (deployState) {
-      const channels = await cloudGet<{ channels: CloudChannel[] }>(
-        parseCloudApiUrl(args.flags.api),
-        `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
-      );
-      printChannelsTable(channels.channels);
-      return;
-    }
-
-    const capsule = await loadAgentCapsule(process.cwd());
-    printChannelsTable(
-      (capsule.config.channels ?? []).map((channel) => ({
-        id: "",
-        name: channel.name,
-        type: channel.type,
-        provider: channel.provider,
-        status: "local_config",
-        webhook_url: "",
-        required_secrets: channel.secrets.map((name) => ({ name, status: "missing" })),
-      })),
-    );
-    return;
-  }
-
-  if (subcommand === "add") {
-    const type = first;
-    const name = second;
-
-    if (!type || !name || (type !== "website" && type !== "telegram" && type !== "whatsapp")) {
-      throw new Error("Usage: agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta]");
-    }
-
-    const deployState = await readDeployStateRequired(process.cwd());
-    const provider = channelProviderForCli(type, args.flags.provider);
-    const payload = {
-      name,
-      type,
-      provider,
-      secrets: defaultChannelSecretsForCli(type, provider),
-    };
-    const response = await cloudPost<{ channel: CloudChannel }>(
-      parseCloudApiUrl(args.flags.api),
-      `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
-      payload,
-    );
-    printChannelStatus(response.channel);
-    return;
-  }
-
-  if (subcommand === "setup") {
-    if (!first) {
-      throw new Error("Usage: agentkit channels setup <name> [--apply]");
-    }
-
-    const channel = await resolveCloudChannelByName(first, args.flags.api);
-    printChannelStatus(channel);
-    if (channel.type === "telegram") {
-      if (args.flags.apply) {
-        await applyTelegramWebhook(channel);
-        console.log("Telegram webhook updated.");
-      } else {
-        console.log(`Setup: call Telegram setWebhook with ${channel.webhook_url}`);
-        console.log("Use --apply to mutate Telegram webhook settings.");
-      }
-    } else if (channel.type === "whatsapp") {
-      console.log(`Next step: paste this URL into ${channel.provider}'s webhook settings.`);
-    } else {
-      console.log(`Website endpoint: ${channel.webhook_url}`);
-      console.log("Use this endpoint from the AgentKit website client or a signed server-to-server test.");
-    }
-    return;
-  }
-
-  if (subcommand === "status") {
-    if (!first) {
-      throw new Error("Usage: agentkit channels status <name>");
-    }
+async function requireLocalDeployState(): Promise<LocalDeployState> {
+  const state = await readLocalDeployStateIfExists(process.cwd());
 
-    const channel = await resolveCloudChannelByName(first, args.flags.api);
-    printChannelStatus(channel);
-    await printChannelDeliverySummary(channel, args.flags.api);
-    return;
+  if (!state) {
+    throw new Error("No .agentkit/deploy.json found. Run agentkit deploy first.");
   }
 
-  if (subcommand === "test") {
-    if (!first) {
-      throw new Error('Usage: agentkit channels test <name> [--message "hello"] [--fixture <path>]');
-    }
-
-    const channel = await resolveCloudChannelByName(first, args.flags.api);
-    const apiUrl = parseCloudApiUrl(args.flags.api);
-    const body = await channelTestBody(channel, args.flags.message, args.flags.fixture);
-    const path = new URL(channel.webhook_url).pathname;
-    const headers = channelTestHeaders(channel);
-    const response = await cloudFetch(apiUrl, path, {
-      method: channel.type === "whatsapp" && channel.provider === "meta" ? "POST" : "POST",
-      headers,
-      body,
-    });
-    const payload = await response.json();
+  return state;
+}
 
-    console.log(JSON.stringify(payload, null, 2));
-    if (!response.ok) {
-      process.exitCode = 1;
-    }
-    return;
+function requireDeployUrl(state: Pick<LocalDeployState, "deploy_id" | "url">): string {
+  if (!state.url) {
+    throw new Error(`Deploy ${state.deploy_id} does not have a URL. Run agentkit deploy again.`);
   }
 
-  if (subcommand === "deliveries") {
-    if (first === "list") {
-      if (!second) {
-        throw new Error("Usage: agentkit channels deliveries list <name>");
-      }
-
-      const channel = await resolveCloudChannelByName(second, args.flags.api);
-      const response = await cloudGet<{ deliveries: CloudDelivery[] }>(
-        parseCloudApiUrl(args.flags.api),
-        `/v1/channels/${encodeURIComponent(channel.id)}/deliveries`,
-      );
-
-      if (response.deliveries.length === 0) {
-        console.log("No channel deliveries found.");
-        return;
-      }
-
-      console.log("ID\tCHANNEL\tDIRECTION\tSTATUS\tPROVIDER_EVENT\tRECEIVED");
-      for (const delivery of response.deliveries) {
-        console.log(
-          [
-            delivery.id,
-            delivery.channel_id,
-            delivery.direction,
-            delivery.status,
-            delivery.provider.event_id ?? "",
-            delivery.received_at,
-          ].join("\t"),
-        );
-      }
-      return;
-    }
-
-    if (first === "show") {
-      if (!second) {
-        throw new Error("Usage: agentkit channels deliveries show <delivery-id>");
-      }
+  return state.url;
+}
 
-      const response = await cloudGet<{ delivery: CloudDelivery }>(
-        parseCloudApiUrl(args.flags.api),
-        `/v1/channel-deliveries/${encodeURIComponent(second)}`,
-      );
-      console.log(JSON.stringify(response.delivery, null, 2));
-      return;
-    }
+async function readDeployAccessTokenForSmoke(cwd: string, state: LocalDeployState): Promise<string | undefined> {
+  if (state.access?.mode === "public") {
+    return undefined;
   }
 
-  throw new Error(
-    "Usage: agentkit channels list | add | setup | status | test | deliveries list | deliveries show",
-  );
+  const root = await findAgentCapsuleRoot(cwd);
+  return readDeployAccessTokenForUi(join(root, defaultDeployChatAccessTokenPath));
 }
 
-type DeployState = LocalDeployState;
-
-type CloudChannel = {
-  id: string;
-  name: string;
-  type: "website" | "telegram" | "whatsapp";
-  provider: "agentkit" | "telegram" | "zapster" | "meta";
-  status: string;
-  webhook_url: string;
-  required_secrets: Array<{ name: string; status: string }>;
-};
-
-type CloudDelivery = {
-  id: string;
-  channel_id: string;
-  direction: string;
-  status: string;
-  provider: {
-    event_id?: string;
-  };
-  received_at: string;
-};
-
-async function applyTelegramWebhook(channel: CloudChannel): Promise<void> {
-  const botToken = process.env.TELEGRAM_BOT_TOKEN;
-  const secretToken = process.env.TELEGRAM_WEBHOOK_SECRET;
-
-  if (!botToken || !secretToken) {
-    throw new Error("TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET must be set to apply Telegram setup.");
+async function runDeploySmoke(input: { deployUrl: string; message: string; token?: string }): Promise<void> {
+  const headers = new Headers({ "Content-Type": "application/json" });
+
+  if (input.token) {
+    headers.set("Authorization", `Bearer ${input.token}`);
   }
 
   let response: Response;
 
   try {
-    response = await fetch(`https://api.telegram.org/bot${botToken}/setWebhook`, {
+    response = await fetch(new URL("/v1/chat", input.deployUrl).href, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        url: channel.webhook_url,
-        secret_token: secretToken,
-        allowed_updates: ["message"],
-      }),
+      headers,
+      body: JSON.stringify({ message: input.message }),
     });
-  } catch {
-    throw new Error("Telegram setWebhook request failed before Telegram returned a response.");
+  } catch (error) {
+    throw new AgentKitError(
+      "deploy_smoke_failed",
+      `Deploy smoke request failed before a response: ${error instanceof Error ? error.message : String(error)}`,
+    );
   }
 
-  const payload = await response.json().catch(() => ({}));
+  const payload = await response.json().catch(() => null);
 
-  if (!response.ok || !isTelegramOk(payload)) {
-    throw new Error(readTelegramSetupError(payload, response.status));
+  if (!response.ok) {
+    throw new AgentKitError("deploy_smoke_failed", readCloudError(payload, response.status));
   }
-}
 
-function isTelegramOk(payload: unknown): payload is { ok: true } {
-  return Boolean(payload && typeof payload === "object" && "ok" in payload && payload.ok === true);
-}
+  const content =
+    payload && typeof payload === "object" && "message" in payload && isRecord((payload as { message?: unknown }).message)
+      ? (payload as { message: { content?: unknown } }).message.content
+      : undefined;
 
-function readTelegramSetupError(payload: unknown, status: number): string {
-  if (payload && typeof payload === "object" && "description" in payload && typeof payload.description === "string") {
-    return `Telegram setWebhook failed: ${payload.description}`;
+  console.log("");
+  console.log("Deploy smoke verified");
+  console.log(`URL:      ${input.deployUrl}`);
+  console.log(`Message:  ${input.message}`);
+  if (typeof content === "string") {
+    console.log(`Response: ${content}`);
   }
-
-  return `Telegram setWebhook failed with HTTP ${status}.`;
 }
 
-async function readDeployStateIfExists(cwd: string): Promise<DeployState | null> {
-  return readLocalDeployStateIfExists(cwd);
+function printJson(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2));
 }
 
-async function readDeployStateRequired(cwd: string): Promise<DeployState> {
-  const state = await readDeployStateIfExists(cwd);
-
-  if (!state?.deploy_id) {
-    throw new Error("No .agentkit/deploy.json found. Run agentkit deploy before creating hosted channels.");
-  }
-
-  return state;
-}
+async function printJsonOrWrite(value: unknown, outFlag: string | boolean | undefined, usage: string): Promise<void> {
+  const outPath = parseOptionalStringFlag(outFlag, "out", usage);
 
-function printChannelsTable(channels: CloudChannel[]): void {
-  if (channels.length === 0) {
-    console.log("No channels found.");
+  if (!outPath) {
+    printJson(value);
     return;
   }
 
-  console.log("NAME\tTYPE\tPROVIDER\tSTATUS\tLAST_EVENT");
-  for (const channel of channels) {
-    console.log([channel.name, channel.type, channel.provider, channel.status, ""].join("\t"));
-  }
-}
-
-function printChannelStatus(channel: CloudChannel): void {
-  console.log(`Channel: ${channel.name}`);
-  if (channel.id) {
-    console.log(`ID: ${channel.id}`);
-  }
-  console.log(`Type: ${channel.type}`);
-  console.log(`Provider: ${channel.provider}`);
-  console.log(`Status: ${channel.status}`);
-  if (channel.webhook_url) {
-    console.log(`Webhook URL: ${channel.webhook_url}`);
-  }
-  console.log("Required secrets:");
-  for (const secret of channel.required_secrets) {
-    console.log(`  ${secret.name}: ${secret.status}`);
-  }
+  const absolutePath = resolve(process.cwd(), outPath);
+  await writeSecretJson(absolutePath, value);
+  console.log(`Deploy access token written to ${absolutePath}`);
 }
 
-async function printChannelDeliverySummary(
-  channel: CloudChannel,
-  apiFlag: string | boolean | undefined,
-): Promise<void> {
-  const response = await cloudGet<{ deliveries: CloudDelivery[] }>(
-    parseCloudApiUrl(apiFlag),
-    `/v1/channels/${encodeURIComponent(channel.id)}/deliveries`,
-  );
-  const inbound = [...response.deliveries].reverse().find((delivery) => delivery.direction === "inbound");
-  const outbound = [...response.deliveries].reverse().find((delivery) => delivery.direction === "outbound");
-
-  console.log("Recent delivery:");
-  console.log(`  Last inbound: ${inbound ? `${inbound.status} ${inbound.received_at}` : "none"}`);
-  console.log(`  Last outbound: ${outbound ? `${outbound.status} ${outbound.received_at}` : "none"}`);
-  console.log("Provider health: not_checked");
+function relativePath(root: string, path: string): string {
+  const output = relative(root, path);
+  return output.startsWith("..") ? path : output || ".";
 }
 
-async function resolveCloudChannelByName(name: string, apiFlag: string | boolean | undefined): Promise<CloudChannel> {
-  const deployState = await readDeployStateRequired(process.cwd());
-  const response = await cloudGet<{ channels: CloudChannel[] }>(
-    parseCloudApiUrl(apiFlag),
-    `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
-  );
-  const channel = response.channels.find((candidate) => candidate.name === name);
-
-  if (!channel) {
-    throw new Error(`Channel "${name}" was not found for deploy ${deployState.deploy_id}.`);
-  }
-
-  return channel;
-}
-
-function channelProviderForCli(type: string, providerFlag: string | boolean | undefined): string {
-  if (type === "website") {
-    return "agentkit";
-  }
-
-  if (type === "telegram") {
-    return "telegram";
-  }
-
-  const provider = providerFlag ?? "zapster";
-
-  if (provider !== "zapster" && provider !== "meta") {
-    throw new Error('WhatsApp provider must be "zapster" or "meta".');
-  }
-
-  return provider;
-}
-
-function defaultChannelSecretsForCli(type: string, provider: string): string[] {
-  if (type === "website") {
-    return ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"];
-  }
-
-  if (type === "telegram") {
-    return ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"];
-  }
-
-  if (type === "whatsapp" && provider === "zapster") {
-    return ["ZAPSTER_API_KEY", "ZAPSTER_WEBHOOK_SECRET"];
-  }
-
-  if (type === "whatsapp" && provider === "meta") {
-    return ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"];
-  }
-
-  return [];
-}
-
-async function channelTestBody(
-  channel: CloudChannel,
-  messageFlag: string | boolean | undefined,
-  fixtureFlag: string | boolean | undefined,
-): Promise<string> {
-  if (typeof fixtureFlag === "string") {
-    return readFile(resolve(process.cwd(), fixtureFlag), "utf8");
-  }
-
-  const message = typeof messageFlag === "string" ? messageFlag : "hello";
-
-  if (channel.type === "telegram") {
-    return JSON.stringify({
-      update_id: Date.now(),
-      message: {
-        message_id: 1,
-        chat: { id: 456, type: "private" },
-        from: { id: 123, first_name: "AgentKit" },
-        text: message,
-      },
-    });
-  }
-
-  if (channel.type === "whatsapp") {
-    return JSON.stringify({
-      event_id: `evt_${Date.now()}`,
-      instance_id: "local",
-      message: {
-        id: `msg_${Date.now()}`,
-        from: "5511999999999",
-        type: "text",
-        text: { body: message },
-      },
-    });
-  }
-
-  return JSON.stringify({
-    event_id: `web_${Date.now()}`,
-    visitor_id: "visitor_test",
-    message: {
-      id: `msg_${Date.now()}`,
-      text: message,
-    },
-  });
-}
-
-function channelTestHeaders(channel: CloudChannel): Headers {
-  const headers = new Headers({ "Content-Type": "application/json" });
-
-  if (channel.type === "website") {
-    const token = process.env.AGENTKIT_WEBSITE_CHANNEL_TOKEN;
-
-    if (token) {
-      headers.set("Authorization", `Bearer ${token}`);
-    }
-  }
-
-  if (channel.type === "telegram") {
-    headers.set("X-Telegram-Bot-Api-Secret-Token", process.env.TELEGRAM_WEBHOOK_SECRET ?? "");
-  }
-
-  if (channel.type === "whatsapp" && channel.provider === "zapster") {
-    headers.set("X-Zapster-Webhook-Secret", process.env.ZAPSTER_WEBHOOK_SECRET ?? "");
-  }
-
-  return headers;
-}
-
-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;
-}
-
-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;
-}
-
-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,
-  });
-}
-
-type CloudAuthConfig = {
-  apiUrl: string;
-  token: string;
-  source?: "environment" | "file";
-};
-
-function cloudAuthPath(): string {
-  return join(homedir(), ".agentkit", "cloud.json");
-}
-
-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;
-}
-
-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 });
-}
-
-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 });
-}
-
-async function resolveCloudApiUrl(flag: string | boolean | undefined): Promise<string> {
-  if (flag !== undefined) {
-    return parseCloudApiUrl(flag);
-  }
-
-  const auth = await readCloudAuth();
-  return auth?.apiUrl ?? parseCloudApiUrl(undefined);
-}
-
-async function requireLocalDeployState(): Promise<LocalDeployState> {
-  const state = await readLocalDeployStateIfExists(process.cwd());
-
-  if (!state) {
-    throw new Error("No .agentkit/deploy.json found. Run agentkit deploy first.");
-  }
-
-  return state;
-}
-
-async function resolveProjectIdForSecretCommand(cwd: string): Promise<string> {
-  const state = await readLocalDeployStateIfExists(cwd);
-
-  if (state?.project_id) {
-    return state.project_id;
-  }
-
-  const root = await findAgentCapsuleRoot(cwd);
-  const capsule = await loadAgentCapsule(root);
-  return stableCloudProjectId(capsule.config.name);
-}
-
-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;
-}
-
-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;
-    if (typeof error?.message === "string") {
-      return error.message;
-    }
-  }
-
-  return `AgentKit Cloud request failed with HTTP ${status}.`;
-}
-
-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: ${usage}`);
-  }
-
-  const port = Number(value);
-
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    throw new Error(`Invalid port. Usage: ${usage}`);
-  }
-
-  return port;
-}
-
-function parseTargetFlag(value: string | boolean | undefined, capability: "build" | "deploy"): string {
-  if (value === undefined) {
-    return "cloudflare";
-  }
-
-  if (typeof value !== "string") {
-    throw new Error(
-      `Missing target. Usage: agentkit ${capability} --target ${listTargetsWithCapability(capability).join("|")}`,
-    );
-  }
-
-  return value;
-}
-
-function parseCloudApiUrl(value: string | boolean | undefined): string {
-  if (value === undefined) {
-    return process.env.AGENTKIT_CLOUD_API_URL ?? defaultAgentKitCloudApiUrl;
-  }
-
-  if (typeof value !== "string") {
-    throw new Error("Missing API URL. Usage: agentkit deploy --api <url>");
-  }
-
-  return value;
-}
-
-function parseRequiredStringFlag(value: string | boolean | undefined, name: string, usage: string): string {
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`Missing ${name}. Usage: ${usage}`);
-  }
-
-  return value.trim();
-}
-
-function parseOptionalStringFlag(value: string | boolean | undefined, name: string, usage: string): string | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`Missing ${name}. Usage: ${usage}`);
-  }
-
-  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("");
-  console.log(`Target:    ${result.target}`);
-  console.log(`Build dir: ${result.buildDir}`);
-  console.log(`Manifest:  ${result.manifestPath}`);
+function printBuildResult(result: Awaited<ReturnType<typeof buildAgentCapsule>>): void {
+  console.log("AgentKit build complete");
+  console.log("");
+  console.log(`Target:    ${result.target}`);
+  console.log(`Build dir: ${result.buildDir}`);
+  console.log(`Manifest:  ${result.manifestPath}`);
 
   if (result.target === "cloudflare") {
     console.log(`Worker:    ${result.workerPath}`);
@@ -2092,18 +1015,6 @@ async function installProjectDependencies(projectPath: string): Promise<void> {
   }
 }
 
-function runInheritedCommand(command: string, args: string[], cwd: string): Promise<number> {
-  return new Promise((resolvePromise, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      stdio: "inherit",
-    });
-
-    child.once("error", reject);
-    child.once("close", (code) => resolvePromise(code ?? 1));
-  });
-}
-
 async function parseToolInput(
   cwd: string,
   inputFlag: string | boolean | undefined,
@@ -2147,393 +1058,81 @@ 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);
+async function findRunningLocalDevServer(cwd: string): Promise<{ url: string; agent: string } | null> {
+  const capsule = await loadAgentCapsule(cwd);
+  const basePort = localDevBasePort();
 
-  if (!state?.url) {
-    throw new Error("No hosted deploy URL found. Run agentkit deploy first.");
-  }
+  for (let port = basePort; port <= basePort + 50; port += 1) {
+    const state = await fetchLocalAgentKitState(`http://localhost:${port}/_agentkit`);
 
-  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),
-        },
-      });
+    if (state?.agent === capsule.config.name) {
+      return {
+        url: `http://localhost:${port}`,
+        agent: state.agent,
+      };
     }
-  });
-
-  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();
+  return null;
 }
 
-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 localDevBasePort(): number {
+  const value = process.env.AGENTKIT_DEV_BASE_PORT;
 
-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));
-}
+  if (!value) {
+    return defaultAgentKitDevPort;
+  }
 
-function sendHtml(response: ServerResponse, body: string): void {
-  response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-  response.end(body);
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535 ? parsed : defaultAgentKitDevPort;
 }
 
-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);
-      }
+async function fetchLocalAgentKitState(url: string): Promise<{ agent?: string } | null> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 300);
 
-      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;
-      }
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    const payload = await response.json().catch(() => null);
 
-      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>`;
-}
+    if (payload && typeof payload === "object") {
+      return {
+        agent: typeof (payload as { agent?: unknown }).agent === "string" ? (payload as { agent: string }).agent : undefined,
+      };
+    }
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
 
-function escapeHtml(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#39;");
+  return null;
 }
 
-async function waitForShutdown(stop: () => Promise<void>): Promise<void> {
-  await new Promise<void>((resolve) => {
-    let stopped = false;
-
-    const shutdown = () => {
-      if (stopped) {
-        return;
-      }
+async function openLocalUrl(url: string): Promise<void> {
+  if (process.env.AGENTKIT_OPEN_COMMAND === "none") {
+    return;
+  }
 
-      stopped = true;
-      void stop().finally(resolve);
-    };
+  const command =
+    process.env.AGENTKIT_OPEN_COMMAND ??
+    (process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open");
+  const args = process.env.AGENTKIT_OPEN_COMMAND
+    ? [url]
+    : process.platform === "win32"
+      ? ["/c", "start", "", url]
+      : [url];
 
-    process.once("SIGINT", shutdown);
-    process.once("SIGTERM", shutdown);
+  await new Promise<void>((resolvePromise, reject) => {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.once("error", reject);
+    child.once("spawn", () => {
+      child.unref();
+      resolvePromise();
+    });
   });
 }