@andreprado/agentkit 0.1.0-alpha.10

package/src/cli/index.ts

@@ -0,0 +1,1276 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+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 { resolveBuildTarget, resolveDeployTarget } from "../runtime/core/targets";
+import { getConversationFromCwd, listConversationsFromCwd } from "../runtime/conversations";
+import { getConversationTraceFromCwd } from "../runtime/traces";
+import { runAgentMessageFromCwd } from "../runtime/chat";
+import { deployBuildToAgentKitCloud, writeLocalDeployState } from "../runtime/deploy";
+import {
+  migrateLocalDatabase,
+  openLocalDatabaseShell,
+  resetLocalDatabase,
+  seedLocalDatabase,
+} from "../runtime/db-commands";
+import { runEvalsFromCwd, writeEvalFromConversation } from "../runtime/evals";
+import { findAgentKitDocs } from "../runtime/docs";
+import { listCapsuleEnv, setCapsuleEnv, unsetCapsuleEnv } from "../runtime/env";
+import { checkAgentSpec, initializeAgentSpec } from "../runtime/spec";
+import { initializeSyncScaffold, runCapsuleSync } from "../runtime/sync";
+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";
+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";
+import { handleKnowledgeCommand } from "./commands/knowledge";
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.command || args.command === "--help" || args.command === "-h") {
+    console.log(renderHelp());
+    return;
+  }
+
+  if (isHelpRequested(args)) {
+    console.log(renderCommandHelp(args.command));
+    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|dentista] [--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}`);
+    }
+    if (!shouldInstall) {
+      console.log("  npm install");
+    }
+    console.log("  open this folder in Codex or Claude Code");
+    console.log("  coding agents start at skills/agentkit-capsule/SKILL.md");
+    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 `printf %s \"$VALUE\" | npm run agentkit -- env set <NAME> --stdin`.");
+    return;
+  }
+
+  if (args.command === "dev") {
+    const port = parsePort(args.flags.port, "agentkit dev --port <number>");
+    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}`);
+    console.log(`Storage:   ${devServer.storage ?? "managed"}`);
+    console.log("Reload:    prompts/config reload per request; restart after changing tool modules or dependencies");
+    await waitForShutdown(devServer.stop);
+    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>]");
+    }
+
+    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;
+    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" [--conversation-id <id>]');
+    }
+
+    const result = await runAgentMessageFromCwd(process.cwd(), { message, conversationId });
+    console.log(result.message.content);
+    return;
+  }
+
+  if (args.command === "tool") {
+    const [name] = args.positional;
+
+    if (!name) {
+      throw new Error("Missing tool name. Usage: agentkit tool <name> [--input <path-or-json>]");
+    }
+
+    const input = await parseToolInput(process.cwd(), args.flags.input, args.flags["input-json"]);
+    const result = await runToolFromCwd(process.cwd(), { name, input });
+    console.log(JSON.stringify(result.output, null, 2));
+    return;
+  }
+
+  if (args.command === "db") {
+    const [subcommand] = args.positional;
+
+    if (subcommand === "migrate") {
+      const result = await migrateLocalDatabase(process.cwd());
+      console.log("Local database migrated");
+      console.log(`Database: ${result.databasePath}`);
+      console.log(`Migrations: ${result.migrationsPath ?? "none"}`);
+      console.log(`Applied:    ${result.migrationsApplied.length > 0 ? result.migrationsApplied.join(", ") : "none"}`);
+      console.log(`Schema:   ${result.schemaPath ?? "none"}`);
+      return;
+    }
+
+    if (subcommand === "reset") {
+      if (!args.flags.yes) {
+        throw new Error("agentkit db reset deletes the resolved local SQLite database. Re-run with --yes to confirm.");
+      }
+
+      const result = await resetLocalDatabase(process.cwd());
+      console.log("Local database reset");
+      console.log(`Deleted:  ${result.resetPath}`);
+      console.log(`Database: ${result.databasePath}`);
+      console.log(`Migrations: ${result.migrationsPath ?? "none"}`);
+      console.log(`Applied:    ${result.migrationsApplied.length > 0 ? result.migrationsApplied.join(", ") : "none"}`);
+      console.log(`Schema:   ${result.schemaPath ?? "none"}`);
+      return;
+    }
+
+    if (subcommand === "shell") {
+      const result = await openLocalDatabaseShell(process.cwd());
+
+      if (!result.opened) {
+        console.log(result.message);
+        console.log(result.command);
+      } else if (result.exitCode !== 0) {
+        process.exitCode = result.exitCode;
+      }
+
+      return;
+    }
+
+    if (subcommand === "seed") {
+      const seedFile = parseOptionalStringFlag(args.flags.file, "file", "agentkit db seed --file <path>") ?? "seed.sql";
+      const result = await seedLocalDatabase(process.cwd(), seedFile);
+      console.log("Local database seeded");
+      console.log(`Database: ${result.databasePath}`);
+      console.log(`Migrations: ${result.migrationsPath ?? "none"}`);
+      console.log(`Applied:    ${result.migrationsApplied.length > 0 ? result.migrationsApplied.join(", ") : "none"}`);
+      console.log(`Schema:   ${result.schemaPath ?? "none"}`);
+      console.log(`Seed:     ${result.seedPath}`);
+      return;
+    }
+
+    throw new Error("Usage: agentkit db migrate | agentkit db reset --yes | agentkit db shell | agentkit db seed [--file <path>]");
+  }
+
+  if (args.command === "eval") {
+    const [subcommand, conversationId] = args.positional;
+
+    if (subcommand === "from-conversation") {
+      if (!conversationId) {
+        throw new Error("Missing conversation id. Usage: agentkit eval from-conversation <conversation-id> [--out <path>] [--force]");
+      }
+
+      const out = parseOptionalStringFlag(
+        args.flags.out,
+        "out",
+        "agentkit eval from-conversation <conversation-id> --out <path>",
+      );
+      const name = parseOptionalStringFlag(
+        args.flags.name,
+        "name",
+        "agentkit eval from-conversation <conversation-id> --name <name>",
+      );
+      const result = await writeEvalFromConversation(process.cwd(), {
+        conversationId,
+        out,
+        name,
+        force: args.flags.force === true,
+      });
+
+      console.log("Eval created from conversation");
+      console.log(`Conversation: ${result.conversationId}`);
+      console.log(`File:         ${relativePath(result.root, result.file)}`);
+      console.log(`Turns:        ${result.turns}`);
+      return;
+    }
+
+    if (subcommand !== "run") {
+      throw new Error("Usage: agentkit eval run | agentkit eval from-conversation <conversation-id> [--out <path>] [--force]");
+    }
+
+    const summary = await runEvalsFromCwd(process.cwd());
+
+    for (const result of summary.results) {
+      console.log(`${result.passed ? "PASS" : "FAIL"} ${result.name} (${result.file})`);
+
+      for (const failure of result.failures) {
+        console.log(`  - ${failure}`);
+      }
+    }
+
+    console.log("");
+    console.log(`${summary.passed} passed, ${summary.failed} failed`);
+
+    if (summary.failed > 0) {
+      process.exitCode = 1;
+    }
+
+    return;
+  }
+
+  if (args.command === "conversations") {
+    const [subcommand, conversationId] = args.positional;
+
+    if (subcommand === "list") {
+      const conversations = await listConversationsFromCwd(process.cwd());
+
+      if (conversations.length === 0) {
+        console.log("No conversations found.");
+        return;
+      }
+
+      console.log("id\ttitle\tupdated_at\tmessages");
+
+      for (const conversation of conversations) {
+        console.log(
+          [
+            conversation.id,
+            conversation.title ?? "",
+            conversation.updatedAt,
+            String(conversation.messageCount),
+          ].join("\t"),
+        );
+      }
+
+      return;
+    }
+
+    if (subcommand === "show") {
+      if (!conversationId) {
+        throw new Error("Missing conversation id. Usage: agentkit conversations show <conversation-id>");
+      }
+
+      const conversation = await getConversationFromCwd(process.cwd(), conversationId);
+
+      console.log(`id: ${conversation.id}`);
+      console.log(`title: ${conversation.title ?? ""}`);
+      console.log(`updated_at: ${conversation.updatedAt}`);
+      console.log("");
+
+      for (const message of conversation.messages) {
+        console.log(`${message.role}: ${message.content}`);
+      }
+
+      return;
+    }
+
+    if (subcommand === "trace") {
+      if (!conversationId) {
+        throw new Error("Missing conversation id. Usage: agentkit conversations trace <conversation-id>");
+      }
+
+      const trace = await getConversationTraceFromCwd(process.cwd(), conversationId);
+      console.log(JSON.stringify(trace, null, 2));
+      return;
+    }
+
+    throw new Error("Usage: agentkit conversations list | agentkit conversations show <conversation-id> | agentkit conversations trace <conversation-id>");
+  }
+
+  if (args.command === "knowledge") {
+    await handleKnowledgeCommand(args);
+    return;
+  }
+
+  if (args.command === "sync") {
+    const [subcommand] = args.positional;
+
+    if (subcommand === "init") {
+      const result = await initializeSyncScaffold(process.cwd(), {
+        force: args.flags.force === true,
+      });
+
+      console.log("Sync scaffold ready");
+      if (result.files.length === 0) {
+        console.log("Files: none written; existing files kept");
+      } else {
+        console.log(`Files: ${result.files.join(", ")}`);
+      }
+      return;
+    }
+
+    if (subcommand === "run") {
+      const file = parseOptionalStringFlag(args.flags.file, "file", "agentkit sync run --file <path>");
+      const result = await runCapsuleSync(process.cwd(), { file });
+
+      console.log("Sync completed");
+      console.log(`File:   ${relativePath(result.root, result.file)}`);
+      console.log(`Output: ${JSON.stringify(result.output)}`);
+      return;
+    }
+
+    throw new Error("Usage: agentkit sync init [--force] | agentkit sync run [--file <path>]");
+  }
+
+  if (args.command === "spec") {
+    const [subcommand] = args.positional;
+
+    if (subcommand === "init") {
+      const brief = parseRequiredStringFlag(
+        args.flags.brief,
+        "brief",
+        'agentkit spec init --brief "agent for a real estate brokerage"',
+      );
+      const out = parseOptionalStringFlag(args.flags.out, "out", "agentkit spec init --out <path>");
+      const result = await initializeAgentSpec(process.cwd(), {
+        brief,
+        out,
+        force: args.flags.force === true,
+      });
+
+      console.log("Agent spec created");
+      console.log(`File: ${relativePath(result.root, result.file)}`);
+      return;
+    }
+
+    if (subcommand === "check") {
+      const file = parseOptionalStringFlag(args.flags.file, "file", "agentkit spec check --file <path>");
+      const result = await checkAgentSpec(process.cwd(), file);
+
+      if (result.ok) {
+        console.log(`Agent spec ok: ${relativePath(result.root, result.file)}`);
+        return;
+      }
+
+      console.log(`Agent spec incomplete: ${relativePath(result.root, result.file)}`);
+      for (const heading of result.missingHeadings) {
+        console.log(`  - missing ## ${heading}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    throw new Error('Usage: agentkit spec init --brief "<owner request>" [--out <path>] [--force] | agentkit spec check [--file <path>]');
+  }
+
+  if (args.command === "inspect") {
+    const state = await inspectAgentCapsule(process.cwd());
+    console.log(JSON.stringify(state, null, 2));
+    return;
+  }
+
+  if (args.command === "build") {
+    const target = resolveBuildTarget(parseTargetFlag(args.flags.target, "build"));
+    const result = await buildAgentCapsule(process.cwd(), { target: target.id });
+    printBuildResult(result);
+    return;
+  }
+
+  if (args.command === "login") {
+    const token = parseRequiredStringFlag(args.flags.token, "token", "agentkit login --token <token> [--api <url>]");
+    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;
+  }
+
+  if (args.command === "logout") {
+    await clearCloudAuth();
+    console.log("AgentKit Cloud token removed.");
+    return;
+  }
+
+  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),
+        requireLogin: !args.flags.anonymous,
+      });
+      printDeployReadinessReport(report);
+
+      if (!report.ok) {
+        process.exitCode = 1;
+      }
+
+      return;
+    }
+
+    if (deploySubcommand === "status" || deploySubcommand === "pause" || deploySubcommand === "resume") {
+      const state = await requireLocalDeployState();
+      const apiUrl = await resolveCloudApiUrl(args.flags.api);
+
+      if (deploySubcommand === "status") {
+        const payload = await cloudApiRequest(apiUrl, `/v1/deploys/${encodeURIComponent(state.deploy_id)}`, {
+          method: "GET",
+        });
+        printJson(payload);
+        return;
+      }
+
+      const payload = await cloudApiRequest(apiUrl, `/v1/deploys/${encodeURIComponent(state.deploy_id)}/${deploySubcommand}`, {
+        method: "POST",
+      });
+      printJson(payload);
+      return;
+    }
+
+    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>");
+      const container = await buildAgentCapsule(process.cwd(), { target: "container" });
+      const plan = await prepareVpsDeploy(container, { host, dryRun: Boolean(args.flags["dry-run"]) });
+      printBuildResult(container);
+      printVpsDeployPlan(plan);
+      return;
+    }
+
+    if (!args.flags["dry-run"] && !args.flags["local-wrangler"]) {
+      const report = await checkDeployReadiness({
+        apiUrl: await resolveCloudApiUrl(args.flags.api),
+        requireLogin: !anonymous,
+      });
+
+      if (!report.ok) {
+        printDeployReadinessReport(report);
+        throw new AgentKitError(
+          "deploy_readiness_failed",
+          "Fix deploy readiness failures before running agentkit deploy.",
+        );
+      }
+    }
+
+    const result = await buildAgentCapsule(process.cwd(), { target: target.id });
+    if (result.target !== "cloudflare") {
+      throw new Error(`Unsupported AgentKit Cloud deploy target: ${result.target}`);
+    }
+    printBuildResult(result);
+
+    if (args.flags["dry-run"]) {
+      console.log("");
+      console.log("Dry run only. Artifact is ready for AgentKit Cloud.");
+      return;
+    }
+
+    if (args.flags["local-wrangler"]) {
+      await deployCloudflare(result.wranglerPath, result.buildDir);
+      return;
+    }
+
+    const apiUrl = await resolveCloudApiUrl(args.flags.api);
+    const auth = await readCloudAuth();
+    const deploy = await deployBuildToAgentKitCloud(result, {
+      apiUrl,
+      apiToken: auth?.token,
+      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");
+    console.log(`URL:       ${deploy.deploy.url}`);
+    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}`);
+    }
+
+    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;
+  }
+
+  if (args.command === "secret") {
+    const [subcommand, name, ...valueParts] = args.positional;
+    const projectId = await resolveProjectIdForSecretCommand(process.cwd());
+    const apiUrl = await resolveCloudApiUrl(args.flags.api);
+
+    if (subcommand === "list") {
+      const payload = await cloudApiRequest(apiUrl, `/v1/projects/${encodeURIComponent(projectId)}/secrets`, {
+        method: "GET",
+      });
+      printJson(payload);
+      return;
+    }
+
+    if (subcommand === "set") {
+      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>]",
+        inlineSensitiveHelp: "Prefer --stdin, --from-env, or --from-local-env so the value does not enter shell history.",
+      });
+
+      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)}`, {
+        method: "PUT",
+        body: JSON.stringify({ value }),
+      });
+      printJson(payload);
+      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>]");
+      }
+
+      const payload = await cloudApiRequest(apiUrl, `/v1/projects/${encodeURIComponent(projectId)}/secrets/${encodeURIComponent(name)}`, {
+        method: "DELETE",
+      });
+      printJson(payload);
+      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 sync --from-local | 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> [--out <path>] | list | revoke <token-id> [--api <url>]");
+    }
+
+    const state = await requireLocalDeployState();
+    const apiUrl = await resolveCloudApiUrl(args.flags.api);
+
+    if (noun === "create" && name) {
+      const payload = await cloudApiRequest(apiUrl, `/v1/deploys/${encodeURIComponent(state.deploy_id)}/access-tokens`, {
+        method: "POST",
+        body: JSON.stringify({ name }),
+      });
+      await printJsonOrWrite(payload, args.flags.out, "agentkit access token create <name> [--api <url>] [--out <path>]");
+      return;
+    }
+
+    if (noun === "list" && !name) {
+      const payload = await cloudApiRequest(apiUrl, `/v1/deploys/${encodeURIComponent(state.deploy_id)}/access-tokens`, {
+        method: "GET",
+      });
+      printJson(payload);
+      return;
+    }
+
+    if (noun === "revoke" && name) {
+      const payload = await cloudApiRequest(
+        apiUrl,
+        `/v1/deploys/${encodeURIComponent(state.deploy_id)}/access-tokens/${encodeURIComponent(name)}/revoke`,
+        { method: "POST" },
+      );
+      printJson(payload);
+      return;
+    }
+
+    throw new Error("Usage: agentkit access token create <name> [--out <path>] | list | revoke <token-id> [--api <url>]");
+  }
+
+  if (args.command === "channels") {
+    await handleChannelsCommand(args);
+    return;
+  }
+
+  if (args.command === "env") {
+    const [subcommand, name, ...valueParts] = args.positional;
+    const root = await findAgentCapsuleRoot(process.cwd());
+
+    if (subcommand === "list") {
+      const names = await listCapsuleEnv(root);
+
+      if (names.length === 0) {
+        console.log("No local env values set.");
+        return;
+      }
+
+      for (const envName of names) {
+        console.log(`${envName}\tset`);
+      }
+
+      return;
+    }
+
+    if (subcommand === "set") {
+      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]",
+        inlineSensitiveHelp: "Prefer --stdin or --from-env so the value does not enter shell history.",
+      });
+
+      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);
+      console.log(`${name}\tset`);
+      return;
+    }
+
+    if (subcommand === "unset") {
+      if (!name) {
+        throw new Error("Usage: agentkit env unset <NAME>");
+      }
+
+      const removed = await unsetCapsuleEnv(root, name);
+      console.log(`${name}\t${removed ? "unset" : "not_set"}`);
+      return;
+    }
+
+    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") {
+    const [subcommand] = args.positional;
+    const docs = findAgentKitDocs();
+
+    if (!subcommand || subcommand === "path") {
+      console.log(docs.root);
+      return;
+    }
+
+    if (subcommand === "llms") {
+      console.log(docs.llms);
+      return;
+    }
+
+    if (subcommand === "full") {
+      console.log(docs.llmsFull);
+      return;
+    }
+
+    throw new Error("Usage: agentkit docs path | agentkit docs llms | agentkit docs full");
+  }
+
+  if (args.command === "handoff") {
+    const [target = "codex", ...goalParts] = args.positional;
+
+    if (target !== "codex" && target !== "claude") {
+      throw new Error("Usage: agentkit handoff codex [goal] | agentkit handoff claude [goal]");
+    }
+
+    const root = await findAgentCapsuleRoot(process.cwd());
+    const docs = findAgentKitDocs();
+    console.log(renderHandoffPrompt({ target, root, docsLlms: docs.llms, goal: goalParts.join(" ").trim() }));
+    return;
+  }
+
+  throw new Error(`Unknown command: ${args.command}`);
+}
+
+function renderHandoffPrompt(input: { target: string; root: string; docsLlms: string; goal: string }): string {
+  const agentName = input.target === "claude" ? "Claude Code" : "Codex";
+  const skillRouter = join(input.root, "skills/agentkit-capsule/SKILL.md");
+  const skillLine = existsSync(skillRouter) ? `- ${skillRouter}\n` : "";
+  const goal = input.goal
+    ? `Owner request:
+${input.goal}`
+    : `Owner request:
+Use the owner's next natural-language request as the product brief. If they ask for a domain-specific agent, build the first useful local version immediately.`;
+
+  return `You are ${agentName}, working inside this AgentKit Agent Capsule:
+
+${input.root}
+
+Read these files first:
+
+- ${join(input.root, "AGENTKIT.md")}
+${skillLine}- ${input.docsLlms}
+
+${goal}
+
+Rules:
+- Start with the AgentKit capsule skill when it exists.
+- Use llms.txt as the docs router.
+- Read llms-full.txt only when a skill or ambiguous framework behavior requires the complete contract.
+- 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.
+- Make practical assumptions for a first local version and list those assumptions in your final response.
+- Ask follow-up questions only when missing information blocks a safe local implementation.
+
+Verification:
+Run these before you finish:
+
+\`\`\`sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+\`\`\`
+
+If you add a tool, also run a tool smoke test with the fake provider, for example:
+
+\`\`\`sh
+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.
+`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+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 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;
+}
+
+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.`);
+  }
+
+  return state.url;
+}
+
+async function readDeployAccessTokenForSmoke(cwd: string, state: LocalDeployState): Promise<string | undefined> {
+  if (state.access?.mode === "public") {
+    return undefined;
+  }
+
+  const root = await findAgentCapsuleRoot(cwd);
+  return readDeployAccessTokenForUi(join(root, defaultDeployChatAccessTokenPath));
+}
+
+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(new URL("/v1/chat", input.deployUrl).href, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ message: input.message }),
+    });
+  } 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(() => null);
+
+  if (!response.ok) {
+    throw new AgentKitError("deploy_smoke_failed", readCloudError(payload, response.status));
+  }
+
+  const content =
+    payload && typeof payload === "object" && "message" in payload && isRecord((payload as { message?: unknown }).message)
+      ? (payload as { message: { content?: unknown } }).message.content
+      : undefined;
+
+  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}`);
+  }
+}
+
+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 relativePath(root: string, path: string): string {
+  const output = relative(root, path);
+  return output.startsWith("..") ? path : output || ".";
+}
+
+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}`);
+    console.log(`Wrangler:  ${result.wranglerPath}`);
+    if (result.tursoSchemaPath) {
+      console.log(`Turso:     ${result.tursoSchemaPath}`);
+    }
+    console.log(`Bundle:    ${result.bundleSha256}`);
+  }
+
+  if (result.target === "container") {
+    console.log(`Server:    ${result.serverPath}`);
+    console.log(`Docker:    ${result.dockerfilePath}`);
+    console.log(`Migrations:${result.migrationsDir}`);
+  }
+
+  if (result.warnings.length > 0) {
+    console.log("");
+    console.log("Warnings:");
+
+    for (const warning of result.warnings) {
+      console.log(`  - ${warning}`);
+    }
+  }
+}
+
+function printVpsDeployPlan(plan: Awaited<ReturnType<typeof prepareVpsDeploy>>): void {
+  console.log("");
+  console.log("VPS deploy plan ready");
+  console.log(`Host:      ${plan.host}`);
+  console.log(`Compose:   ${plan.composePath}`);
+  console.log(`Env:       ${plan.envExamplePath}`);
+  console.log(`Secrets:   ${plan.secretsPath}`);
+  console.log(`Handoff:   ${plan.handoffPath}`);
+  console.log(`State:     ${plan.statePath}`);
+  console.log("");
+  console.log("Commands:");
+
+  for (const command of plan.commands) {
+    console.log(`  ${command}`);
+  }
+}
+
+async function deployCloudflare(wranglerPath: string, buildDir: string): Promise<void> {
+  const exitCode = await runInheritedCommand("npx", ["wrangler", "deploy", "--config", wranglerPath], buildDir);
+
+  if (exitCode !== 0) {
+    throw new Error(`Cloudflare deploy failed with exit code ${exitCode}.`);
+  }
+}
+
+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}.`);
+  }
+}
+
+async function parseToolInput(
+  cwd: string,
+  inputFlag: string | boolean | undefined,
+  inputJsonFlag: string | boolean | undefined,
+): Promise<unknown> {
+  if (inputFlag === undefined && inputJsonFlag === undefined) {
+    return {};
+  }
+
+  if (inputFlag !== undefined && inputJsonFlag !== undefined) {
+    throw new Error("Use either --input <path-or-json> or --input-json <json>, not both.");
+  }
+
+  if (inputJsonFlag !== undefined) {
+    if (typeof inputJsonFlag !== "string") {
+      throw new Error("Missing JSON. Usage: agentkit tool <name> --input-json '<json>'");
+    }
+
+    return parseJsonInput(inputJsonFlag, "--input-json");
+  }
+
+  if (typeof inputFlag !== "string") {
+    throw new Error("Missing input. Usage: agentkit tool <name> --input <path-or-json>");
+  }
+
+  const trimmed = inputFlag.trim();
+
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    return parseJsonInput(trimmed, "--input");
+  }
+
+  const contents = await readFile(resolve(cwd, inputFlag), "utf8");
+  return parseJsonInput(contents, inputFlag);
+}
+
+function parseJsonInput(source: string, label: string): unknown {
+  try {
+    return JSON.parse(source);
+  } catch (error) {
+    throw new Error(`${label} must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+async function findRunningLocalDevServer(cwd: string): Promise<{ url: string; agent: string } | null> {
+  const capsule = await loadAgentCapsule(cwd);
+  const basePort = localDevBasePort();
+
+  for (let port = basePort; port <= basePort + 50; port += 1) {
+    const state = await fetchLocalAgentKitState(`http://localhost:${port}/_agentkit`);
+
+    if (state?.agent === capsule.config.name) {
+      return {
+        url: `http://localhost:${port}`,
+        agent: state.agent,
+      };
+    }
+  }
+
+  return null;
+}
+
+function localDevBasePort(): number {
+  const value = process.env.AGENTKIT_DEV_BASE_PORT;
+
+  if (!value) {
+    return defaultAgentKitDevPort;
+  }
+
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535 ? parsed : defaultAgentKitDevPort;
+}
+
+async function fetchLocalAgentKitState(url: string): Promise<{ agent?: string } | null> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 300);
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    const payload = await response.json().catch(() => null);
+
+    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);
+  }
+
+  return null;
+}
+
+async function openLocalUrl(url: string): Promise<void> {
+  if (process.env.AGENTKIT_OPEN_COMMAND === "none") {
+    return;
+  }
+
+  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];
+
+  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();
+    });
+  });
+}
+
+main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  const prefix = isAgentKitError(error) ? `agentkit ${error.code}` : "agentkit";
+  console.error(`${prefix}: ${message}`);
+  process.exitCode = 1;
+});