@cursor/bdk 0.2.1

package/src/bin/agent-serve.ts

@@ -0,0 +1,1833 @@
+#!/usr/bin/env node
+/**
+ * agent-serve CLI.
+ *
+ *   agent-sdk serve      [--dir .] [--port 3000] [--host 127.0.0.1] [--dev]
+ *   agent-sdk dev        [path] [--port 3000] [--host 127.0.0.1]
+ *   agent-sdk docs       [--port 0] [--host 127.0.0.1] [--print]
+ *   agent-sdk chat      [--url http://127.0.0.1:3000] [--message "..."] [--json]
+ *   agent-sdk resume    [sessionId] [--url | --prod] [--message "..."]
+ *   agent-sdk run       [--dir .] [--message "..."] [--json|--text]
+ *   agent-sdk trajectory --events <file.ndjson>
+ *   agent-sdk init      [dir] [--json]
+ *   agent-sdk convert-automation <url> [--dir <path>] [--json]
+ *   agent-sdk eval        [--dir .] [evalId...]
+ *   agent-sdk validate   [--dir .]
+ *   agent-sdk slack     <subcommand>
+ */
+
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { formatDiagnostics, projectInfo, resolveAgentMounts, serve } from "../index.js";
+import { registerAuthoredModuleLoaders } from "../internal/authored-loaders.js";
+import {
+  type AxCliOptions,
+  cmdCall,
+  cmdChat,
+  cmdCost,
+  cmdEval,
+  cmdEvalCancel,
+  cmdEvalStatus,
+  cmdInit,
+  cmdLogs,
+  cmdPlayground,
+  cmdResume,
+  cmdRun,
+  cmdSession,
+  cmdSessions,
+  cmdSkill,
+  cmdTrajectory,
+} from "../internal/cli-ax.js";
+import {
+  cmdCancelRuns,
+  cmdDelete,
+  cmdDeploy,
+  cmdDeploymentStatus,
+  cmdDeployments,
+  cmdEventRepos,
+  cmdKill,
+  cmdRotateToken,
+  cmdSecretsList,
+  cmdSecretsSet,
+  cmdSecretsUnset,
+  cmdStart,
+  cmdStop,
+  cmdUnlockDeploys,
+  cmdUpgrade,
+  type DeployCliOptions,
+} from "../internal/cli-deploy.js";
+import { cmdImagesList, cmdImagesPush, cmdImagesRm } from "../internal/cli-images.js";
+import { cmdManifest } from "../internal/cli-manifest.js";
+import {
+  CLI_COMMAND_NAME as CLI,
+  formatCliVersion,
+  PACKAGE_NAME,
+  packageVersion,
+} from "../internal/distribution.js";
+import { loadAgentLocalEnv } from "../internal/local-env.js";
+import {
+  ENTER_RESTART_EXIT_CODE,
+  isServeRestartWorker,
+  runEnterRestartSupervisor,
+} from "../internal/serve-restart.js";
+import { flushSessionRunFatal } from "../internal/session-run-log.js";
+import { clearTerminal, stdoutPalette } from "../internal/terminal-style.js";
+import { cmdUpdate, warnIfOutdated } from "../internal/update-check.js";
+import type { AgentProject, AgentServeHandle } from "../types.js";
+
+const HELP = `${CLI} — serve a filesystem-defined Cursor agent over channels
+
+Usage:
+  ${CLI} serve       [--dir <path>] [--port <n>] [--host <host>] [--dev]
+                          [--mode single|multi] [--api-key <key>] [--no-schedules]
+                          [--public-url <url>]
+                          [--cursor-events --repo <owner/name>]...
+  ${CLI} dev         [path] [--port <n>] [--host <host>] …
+                          Same flags as serve; implies --dev. Path defaults to
+                          the current directory (or pass --dir).
+  ${CLI} chat        [--url <baseUrl> | --prod] [--message <text>] [--json] [--text]
+                          [--session <id> | --resume] [--continuation-token <t>]
+                          [--slug <slug>] [--team <id>]
+  ${CLI} resume      [sessionId] [--url <baseUrl> | --prod] [--message <text>]
+                          [--json] [--text] [--continuation-token <t>]
+                          [--slug <slug>] [--team <id>]
+  ${CLI} logs        [--url <baseUrl> | --prod] [--once] [--json]
+                          [--slug <slug>] [--team <id>] [--dir <path>]
+  ${CLI} sessions    [--url <baseUrl> | --prod] [--json]
+                          [--slug <slug>] [--team <id>] [--dir <path>]
+  ${CLI} session     <sessionId> [--url <baseUrl> | --prod]
+                          [--json | --text | --events] [--out <file.ndjson>]
+                          [--slug <slug>] [--team <id>] [--dir <path>]
+                 or: --prod [<sessionId>] --slug <slug> --message "…" [--dry-run] [--as-of <instant>]
+  ${CLI} cost        [sessionId] [--url <baseUrl> | --prod] [--json]
+                          [--slug <slug>] [--team <id>] [--dir <path>]
+  ${CLI} playground  [--url <baseUrl> | --prod] [--session <id>] [--print]
+                          [--slug <slug>] [--team <id>] [--dir <path>]
+  ${CLI} docs        [--port <n>] [--host <host>] [--print]
+  ${CLI} run         [--dir <path>] [--message <text>]... [--url <baseUrl> | --prod]
+                          [--session <id>] [--continuation-token <t>]
+                          [--events <file.ndjson>] [--no-events] [--text]
+                          [--timeout-ms <n>] [--no-stream] [--slug <slug>] [--team <id>]
+                          [--dry-run] [--as-of <instant>]
+  ${CLI} trajectory  --events <file.ndjson> [--text]
+  ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
+                          [--session <id>] [--slug <slug>] [--team <id>]
+  ${CLI} skill       <name> [--dir <path> | --url <baseUrl> | --prod]
+                          [--slug <slug>] [--team <id>] [--text]
+  ${CLI} init        [dir] [--template <name>] [--var id=value]... [--json]
+  ${CLI} convert-automation <url> [--dir <path>] [--json]
+  ${CLI} install-skills [--print] [--json]
+  ${CLI} mcp         --prod [--slug <slug>] [--team <id>] [--dir <path>]
+                          | --url <baseUrl> [--bearer-token <t>]
+  ${CLI} mcp install [--name <serverName>] [--print] [--json]
+                          (same target flags as mcp)
+  ${CLI} mcp oauth   <connection> [--dir <path>] [--store] [--slug <slug>]
+  ${CLI} eval        [--dir <path>] [evalId...] [--list] [--json]
+                          [--tag <tag>]... [--verbose] [--timeout-ms <n>]
+                          [--strict] [--max-concurrency <n>]
+                          [--junit <path>] [--artifacts <dir>|--no-artifacts]
+                          [--out <file.json>]
+                          [--skip-report] [--no-stream] [--no-wait]
+                          [--prod | --url <baseUrl>] [--slug <slug>]
+                          [--team <id>]
+  ${CLI} eval status [runId] --prod|--url <baseUrl> [--dir <path>] [--json]
+                          [--out <file.json>] [--slug <slug>] [--team <id>]
+  ${CLI} eval cancel <runId> --prod|--url <baseUrl> [--dir <path>] [--json]
+                          [--slug <slug>] [--team <id>]
+  ${CLI} info        [--dir <path>] [--json]
+  ${CLI} validate    [--dir <path>]
+  ${CLI} login       [--api-key <key>] [--key-name <name>]
+  ${CLI} logout
+  ${CLI} whoami      [--json]
+  ${CLI} update
+  ${CLI} version     [--json]
+  ${CLI} deploy      [--dir <path>] [--slug <slug> | --all] [--team <id>] [--json]
+                          [--no-wait] [--repo <url>] [--ref <ref>]
+                          [--path <agentPath>] [--cursor-events-repo <owner/name>]...
+                          [--allow-domain <domain>]...
+  ${CLI} manifest    [--dir <path>] [--json]
+  ${CLI} deployments [--team <id>] [--json]
+  ${CLI} deployment  <slug> [--team <id>] [--json]
+  ${CLI} stop        <slug> [--team <id>] [--json] [--no-wait] [--cancel-runs]
+  ${CLI} start       <slug> [--team <id>] [--json]
+  ${CLI} kill        <slug> [--team <id>] [--json]
+  ${CLI} unlock-deploys <slug> [--team <id>] [--json]
+  ${CLI} cancel-runs <slug> [--team <id>] [--json]
+  ${CLI} event-repos <slug> [--repo <owner/name>]... [--team <id>] [--json]
+  ${CLI} upgrade     <slug> [--release <id|version>] [--team <id>] [--json]
+  ${CLI} delete      <slug> [--team <id>] [--json] [--no-wait]
+  ${CLI} rotate-token <slug> [--team <id>]
+  ${CLI} secrets     set <slug> NAME... | list <slug> | unset <slug> NAME
+                          [--team <id>] [--json] [--from-argv]
+  ${CLI} slack       <subcommand> …
+  ${CLI} github      <subcommand> …
+
+Commands:
+  serve       Serve agents under /<slug>/... (index at /). Runs \`${CLI} login\`
+              when unsigned. On a TTY, press Enter to restart (re-executes this
+              process so agent code, evals, and Vite reload).
+  dev         Local development: same as \`${CLI} serve --dev\` (manual
+              schedule/reminder dispatch, unsigned GitHub loopback, Vite HMR).
+              Also runs \`${CLI} login\` when unsigned.
+  chat        Interactive REPL against a running server (follow-ups keep the
+              session + continuation token). Optional --message seeds the first
+              turn then stays open on a TTY. --session reattaches (looks up the
+              continuation token via /v1/sessions when omitted) and replays the
+              transcript. --resume reattaches the most recently updated
+              followable session (no id needed). --json is one-shot. Pass
+              --prod to hit the team's hosted deployment (slug from --slug or
+              the directory name).
+  resume      Reattach chat to a session (same as \`${CLI} chat --session <id>\`
+              or \`${CLI} chat --resume\` with no id). Omit the session id to
+              resume the previous followable session from /v1/sessions. Looks
+              up the continuation token via /v1/sessions when
+              --continuation-token is omitted, then replays the transcript.
+              Pass --prod for a hosted deployment.
+  logs        Tail agent logs. Default follows (Ctrl-C to stop); --once dumps
+              the current buffer. --prod shows deploy progress until the
+              hosted deployment is running, then tails runtime logs. Without
+              --prod, tails the local server (or --url).
+  sessions    List sessions on a running agent (or --prod hosted deployment).
+  session     Show one session. Default: text trajectory. --json for trajectory
+              JSON; --events for the raw event list. To continue interactively,
+              use \`${CLI} resume [id]\`.
+  cost        Pull cost metrics. With a session id: per-turn token usage and
+              estimated cost for that session. Without one: one row per
+              session plus a total. Costs are the engine's recorded estimates
+              from turn.completed events; --json for machine-readable reports.
+  playground  Open the web playground. --prod opens the v1 hosted alias or
+              v2 portal UI; --session deep-links a session. --print skips
+              opening a browser. Ctrl-C stops local credential proxies.
+  docs        Serve the shipped documentation site on loopback and open it
+              (also: npx @cursor/bdk docs). No agent project required.
+              --print skips opening a browser. Ctrl-C stops the server.
+  run         One-shot create→test loop: ephemeral server + JSON trajectory.
+              Writes a single events.ndjson trace (summarize with trajectory).
+              Streams tool calls and reply text to stderr when stderr is a TTY.
+              Pass --prod to hit the hosted deployment instead of a local server.
+              On an AgentSDK v2 slug, --prod starts a hosted session through
+              the control plane (Temporal, no resident engine); --session
+              ses_… resumes that exact session. A 404 falls back to the v1
+              engine alias.
+  trajectory  Summarize an events.ndjson file into a trajectory.
+  call        Call an authored server tool deterministically (no model turn)
+              via POST /v1/tools/:toolName. --session runs it inside an
+              existing session and records it on that session's event stream.
+  skill       Read an authored skill deterministically (no model turn)
+              via GET /v1/skills/:skillName. --text prints SKILL.md.
+  init        Scaffold a project (skipping existing files), npm install,
+              run login when unsigned, then print next steps. Templates
+              with init.json interview on a TTY; --var answers without a
+              prompt. --json is machine-readable and never blocks on
+              login. No directory: print the setup guide.
+  convert-automation
+              Export a Cursor Automation into an agentsdk project. <url> is
+              the dashboard URL (…/automations/<uuid> or
+              …/custom-agents/<uuid>) or a bare uuid. Fetches the definition
+              with your Cursor credentials, writes the converted files into
+              --dir (default ./<automation-name>), fills in the init scaffold
+              around them (existing files are kept), and installs npm
+              dependencies. MCP servers convert to Cursor-account connections
+              resolved at runtime (manage authorization in Cursor, dashboard
+              -> MCP). Review the project, then run \`validate\` / \`dev\`.
+              Warnings never fail the command.
+  install-skills
+              Refresh the Agent SDK skills for coding agents in
+              ~/.cursor/skills/agentsdk and print where they landed.
+              Installed copies set alwaysApply so Cursor injects them
+              into context. \`npm install\` / \`npx\` already copies them
+              (postinstall); this command overwrites with the package
+              version without asking. \`init\` also offers a TTY refresh.
+              --print previews without writing.
+  mcp         Serve this agent's MCP endpoint over stdio for MCP clients
+              that spawn local servers (e.g. Cursor). Proxies
+              newline-delimited JSON-RPC to <target>/v1/mcp. --prod resolves
+              the hosted deployment with the signed-in Cursor account and
+              re-mints short-lived engine credentials as they expire;
+              --url targets a running server. stdout is reserved for the
+              MCP wire. \`mcp install\` writes the matching entry into
+              ~/.cursor/mcp.json (--print to preview; --name to override
+              the server name). \`mcp oauth <connection>\` runs host PKCE
+              for defineConnection({ url, oauth: true }); \`--store\` upserts
+              MCP_OAUTH_<NAME>_* secrets on the hosted deployment.
+  eval        Run filesystem evals under evals/**/*.eval.ts (streams on a TTY).
+              Default: ephemeral local harness against evals on disk. Pass
+              --prod to kick off the batch on the team's hosted deployment
+              (slug from --slug or the directory name) via /v1/dev/evals/runs
+              so results appear in the playground and persist when the agent
+              declares an evals storage table; or --url for a running server
+              (same server-side path).               With --prod/--url, prints an Eval ID as soon as the batch is
+              accepted (also with --no-wait). Check later with
+              \`${CLI} eval status <evalId> --prod\` (omit id to list recent
+              runs; exit 3 while still running) or cancel with
+              \`${CLI} eval cancel <evalId> --prod\`. The status/cancel
+              subcommands only bind when --prod/--url is set, so an eval id
+              named status/cancel still runs locally. Pass evalId args to
+              select: one datapoint (weather/nyc), a whole file (weather → all
+              cases in that file), several of either, or omit to run all.
+  info        Print the discovered agent surface (tools, skills, channels, ...).
+  validate    Check the project(s) and exit non-zero on error diagnostics.
+  login       Sign the host in to Cursor: browser sign-in mints a named,
+              dashboard-revocable API key (only the key is stored). It powers
+              inference and cursorAccount MCP connections.
+  logout      Remove the stored Cursor credentials.
+  whoami      Show which Cursor account powers this host (and why).
+  update      Upgrade this install to the latest published version (detects
+              global npm/pnpm/yarn/bun installs and project dependencies).
+  version     Print the ${PACKAGE_NAME} version this CLI will use and exit
+              (also --version / -V). Text is the version number; --json
+              prints { name, version, cli }.
+  deploy      Deploy onto Cursor's managed agent-serve hosting, then wait for
+              the engine to come up. --repo/--ref/--path stay available;
+              inside an agent git checkout they are inferred when omitted
+              (flags always win). When --dir is a multi-agent parent,
+              pick one interactively, or pass --slug / --all. First deploy
+              of a slug prints the alias token exactly once — save it.
+  deployments List the team's deployments (slug, status, generation, kind).
+  deployment  Show one deployment in full (status, lastError, engine info).
+  stop        Stop every install of a slug and wait until it reports
+              stopped. Does not lock deploys or flip tenant enabled.
+  start       Resume every enabled install of a slug. Does not unlock
+              deploys; run unlock-deploys first after kill.
+  kill        Emergency stop: lock deploys, stop every install, cancel
+              runs and reminder clocks.
+  unlock-deploys Allow deploy/upgrade again after kill. Does not resume
+              traffic; start after unlock.
+  cancel-runs Request cancellation for active Agent SDK v2 session runs
+              and reminder clocks, and mark factory creating/active
+              sessions failed. For a multi-tenant application this
+              cancels every install, not just the caller's.
+              Install-local cancel is stop --cancel-runs.
+  event-repos Set the repositories a multi-tenant install receives events
+              for. A deploy cannot carry these; pass every repository you
+              want, since the list is replaced rather than merged.
+  upgrade     Move this team's install onto a release, the newest ready one
+              by default. Deploying a multi-tenant application publishes a
+              release without moving any tenant onto it.
+  delete      Delete a deployment (teardown + purge the record) and wait
+              until GET 404s. The slug is then free to redeploy.
+  rotate-token Mint a new alias token for a deployment (shown once); the old
+              token stops working immediately.
+  secrets     Manage deployment secrets: set (names only by default: hidden
+              prompt or piped stdin; NAME=VALUE requires --from-argv), list
+              (names + createdAt; never values), unset.
+  images      Container images for persistent agents: push <local-image>
+              --name <name> (docker save, upload), list, rm <name>.
+  slack       Slack channel pack: create/destroy/icon (dashboard wizard),
+              doctor (see slack help).
+  github      GitHub webhook pack: forward live deliveries, events, doctor
+              (wraps \`gh webhook forward\`; see github help).
+  gitlab      GitLab webhook pack: replay a merge request, events, forward
+              recipe (see gitlab help).
+  bitbucket   Bitbucket webhook pack (Cloud + Data Center): replay a pull
+              request, events, forward recipe (see bitbucket help).
+
+Agent loop:
+  ${CLI} validate --dir .
+  ${CLI} info --dir . --json
+  ${CLI} run --dir . --message "..."
+  ${CLI} eval --dir .
+  ${CLI} eval --prod --dir .
+  ${CLI} dev .
+
+Options:
+  --version, -V      Print the version number and exit.
+  --dir             Project root (defaults to the current directory).
+  --port             Port to listen on (default 3000). When the default is
+                     taken, serve tries the next free port and prints a notice.
+                     An explicit --port fails with a next-port hint instead.
+  --host             Host to bind (default 127.0.0.1).
+  --mode             serve: "multi" (default, slugged /<dir>/v1/*) or "single"
+                     (unslugged /v1/*). Multi also exposes host /v1/health for
+                     ALB/ECS checks; use single when one agent is the whole host.
+  --dev              Dev mode: mounts POST /v1/dev/schedules/:scheduleId and
+                     disables the cron runner (dispatch schedules by hand).
+  --api-key          Cursor API key (defaults to CURSOR_API_KEY, then
+                     CURSOR_API_KEY_FILE — hosted default
+                     /run/cursor/secrets/CURSOR_API_KEY when unset —
+                     then CURSOR_SERVICE_ACCOUNT_KEY, then the stored
+                     \`${CLI} login\` credential).
+  --key-name         login: label for the minted API key (defaults to
+                     "${CLI} (<hostname>)").
+  --state-root       Durable state directory (default <dir>/.agent-serve). Put it
+                     outside any repository whose rules should not reach the agent.
+  --bearer-token     serve: require this bearer token on API routes. chat/run/eval:
+                     send it as the Authorization bearer.
+  --allow-anonymous  serve: admit all HTTP callers (allowAll). For demos behind a
+                     trusted network only; mutually exclusive with --bearer-token.
+  --allow-anonymous-cursor-github
+                     serve: allow --allow-anonymous together with
+                     githubChannel({ cursorAccount }). Admitted callers can drive
+                     sessions holding the account's repo-scoped GitHub credential,
+                     so use only behind a trusted boundary (e.g. an SSO proxy).
+  --allow-anonymous-grokbot
+                     serve: allow --allow-anonymous together with a
+                     runtime: "grokbot" mount. Admitted callers can drive turns
+                     on the signed-in account's hosted Grok Bot computer, so use
+                     only behind a trusted boundary (e.g. an SSO proxy).
+  --allow-anonymous-cursor-account-mcp
+                     serve: allow --allow-anonymous together with
+                     defineConnection({ cursorAccount: true }). Admitted callers
+                     can drive the account's MCP connectors, so use only behind
+                     a trusted boundary (e.g. an SSO proxy or hosted alias token).
+  --cursor-scm-proxy serve: route every SCM channel's cursorAccount API calls
+                     (githubChannel, gitlabChannel, bitbucketChannel) through
+                     the Cursor backend's per-forge forwarder instead of
+                     minting raw tokens into this process
+                     (AGENT_SERVE_<FORGE>_PROXY_URL overrides a base URL).
+  --public-url       serve: base URL where this host is reachable from outside
+                     (e.g. https://agent-serve.example.com).
+  --no-schedules     Disable the cron runner outside dev mode.
+  --no-control-plane serve: do not start the bundled control plane (schedule
+                     and reminder clocks). Cursor hosting passes this so the
+                     kit uses the Cursor backend instead.
+  --team             deploy/deployments/deployment/stop/rotate-token and
+                     chat/resume/run/call/eval/logs/sessions/session/playground
+                     --prod: Cursor team id. Defaults to the account's team when
+                     it has one.
+  --prod             chat/resume/run/call/eval/logs/sessions/session/playground:
+                     use the team's hosted deployment. Slug from --slug or the
+                     --dir basename. Mutually exclusive with --url. Requires
+                     \`${CLI} login\`. For eval, this is how you opt into the
+                     persisted server-side batch (default is local).
+  --dry-run          run/session --prod: mark the hosted v2 turn non-mutating.
+  --component        run/session --prod: wake this v2 component key,
+                     not the application default.
+  --as-of            run/session --prod: freeze the session clock at this
+                     timezone-bearing ISO-8601 instant.
+  --once             logs: print current progress / log buffer once and exit
+                     (default is to follow).
+  --print            playground/docs: print the URL only; do not open a
+                     browser. install-skills: list the skills and the install
+                     path without writing them.
+  --no-wait          deploy/stop/eval: return right after the request is
+                     accepted instead of polling until a terminal status.
+                     For eval, prints the runId (deployment / --url only).
+  --cancel-runs      stop: also cancel this install's active Agent SDK v2
+                     session runs and reminder clocks, and mark factory
+                     creating/active sessions failed (not every tenant).
+  --no-playground    Disable the bundled web playground at /playground (also skips
+                     auto-build / HMR).
+  --no-docs          Disable the documentation site at /docs (also skips its
+                     auto-build).
+  --url              chat/resume/run/call/eval/logs/sessions/session/playground:
+                     base URL of a running agent (skip local host). Mutually
+                     exclusive with --prod.
+  --message          chat/resume/run: user message (repeatable for run).
+  --input            call: JSON object of tool arguments (default {}).
+  --messages-file   JSON array of strings (run).
+  --session          Existing session id (run/call follow-up, or chat reattach).
+                     Prefer \`${CLI} resume [sessionId]\` for interactive
+                     reattach.
+  --resume           chat: reattach the previous followable session (most
+                     recently updated in /v1/sessions). Same as
+                     \`${CLI} resume\` with no session id. Ignored when
+                     --session is also set.
+  --continuation-token  Token from a prior run/chat/resume response (optional
+                     for resume / chat --session/--resume; looked up via
+                     /v1/sessions when omitted).
+  --events           run: write NDJSON trace to this path (default
+                     <dir>/.agent-serve/traces/<sessionId>.ndjson).
+                     trajectory: read this file. session: print raw
+                     { sessionId, events } JSON (boolean; no path).
+  --no-events        run: do not write a trace file.
+  --slug             Agent slug when --dir mounts multiple agents.
+  --timeout-ms       Abort a hung turn after N milliseconds.
+  --tag              eval: only run cases with this tag (repeatable).
+  --list             eval: print discovered cases without running.
+  --verbose          eval: stream t.log lines and reply snippets.
+  --strict           eval: a missed soft threshold (SCORED) also exits 1.
+  --max-concurrency  eval: override evals.config.ts maxConcurrency.
+  --junit            eval: write JUnit XML here for CI annotations.
+  --artifacts        eval: run-artifact directory (default a timestamped dir
+                     under <dir>/.agent-serve/evals/).
+  --no-artifacts     eval: do not write run artifacts.
+  --skip-report      eval: ignore reporters from evals.config.ts / eval files.
+  --no-stream        run/eval: silence live progress on stderr (JSON still prints).
+  --json             JSON output (init/convert-automation/install-skills/
+                     info/chat/eval/logs/version/
+                     sessions/session/github; run defaults to JSON). logs:
+                     NDJSON progress/log events. session: trajectory JSON
+                     (not raw events).
+  --no-color         chat: force plain output.
+  --cursor-events    serve: pull SCM webhook events from /v0/scm-events. The
+                     stream is read as your Cursor user, so serve requires
+                     sign-in (\`${CLI} login\` / CURSOR_API_KEY) and --repo.
+                     Offset under <state-root>/cursor-events/.
+                     CURSOR_API_BASE_URL overrides.
+  --repo             serve --cursor-events: repo to subscribe to (repeatable).
+                     github forward: owner/repo to forward from (inferred from
+                     the git remote when omitted; last wins).
+                     deploy: https git repo URL (optional; inferred from
+                     git remote origin when omitted).
+  --ref              deploy: git ref to build (optional; inferred from the
+                     current branch when omitted).
+  --path             deploy: agent dir relative to repo root (optional;
+                     inferred from --dir vs git toplevel when omitted).
+  --all              deploy: every child agent under a multi-agent --dir
+                     (skips the interactive picker; mutually exclusive with
+                     --slug).
+  --cursor-events-repo  deploy: repo (owner/name) the deployed agent
+                     watches (repeatable).
+  --allow-domain     deploy: egress domain the engine pod may reach
+                     (repeatable; unioned with hosting.egressDomains from the
+                     agent manifest). Repo-backed deploys only.
+  --from-argv        secrets set: allow NAME=VALUE on argv (leaks into shell
+                     history and agent-captured terminals). Default is names
+                     only with a hidden prompt or piped stdin.
+  --org              github forward: organization login (org-level hooks).
+  --channel          github: select one channel id when several are declared.
+  --secret           github forward: webhook signing secret (defaults to
+                     GITHUB_WEBHOOK_SECRET). github: --events overrides the
+                     derived webhook event list.
+  --install          github: install the cli/gh-webhook extension if missing.
+                     slack init --manual: require Slack CLI app install.
+  --no-install       slack init --manual: skip Slack CLI app install.
+  --action           github/gitlab replay: event action (e.g. opened, open).
+  --conclusion       github replay: CI conclusion (check_run/suite/status).
+                     gitlab replay: pipeline status (success, failed, …).
+  --comment          github/gitlab/bitbucket replay: comment / note body.
+  --context          github replay: commit-status context.
+  --dry-run          github replay: print synthesized payloads, don't POST.
+  --out              eval / eval status <runId>: also write the full results
+                     JSON to this path. session: write the raw NDJSON trace
+                     there instead of printing (same format as run --events;
+                     playground-openable). github replay: write synthesized
+                     payloads as fixtures.
+`;
+
+function writeStdout(text: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    process.stdout.write(text, error => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+async function main(argv: string[]): Promise<number> {
+  const [command, ...restIn] = argv;
+  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+    // Await the write: HELP is larger than a pipe buffer, and process.exit
+    // after main() would otherwise truncate --help under execFile / CI.
+    await writeStdout(HELP);
+    return command === undefined ? 1 : 0;
+  }
+  if (command === "version" || command === "--version" || command === "-V") {
+    await writeStdout(formatCliVersion({ json: restIn.includes("--json") }));
+    return 0;
+  }
+
+  // `session --events` means "dump raw events" (boolean). Rewrite so it does
+  // not collide with run/trajectory's `--events <file.ndjson>` string flag.
+  const rest =
+    command === "session" ? restIn.map(arg => (arg === "--events" ? "--raw-events" : arg)) : restIn;
+
+  const { values, positionals } = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    options: {
+      dir: { type: "string", default: "." },
+      template: { type: "string" },
+      var: { type: "string", multiple: true },
+      port: { type: "string" },
+      host: { type: "string" },
+      mode: { type: "string" },
+      dev: { type: "boolean", default: false },
+      "api-key": { type: "string" },
+      "key-name": { type: "string" },
+      "state-root": { type: "string" },
+      "bearer-token": { type: "string" },
+      "allow-anonymous": { type: "boolean", default: false },
+      "allow-anonymous-cursor-github": { type: "boolean", default: false },
+      "allow-anonymous-cursor-account-mcp": { type: "boolean", default: false },
+      "allow-anonymous-grokbot": { type: "boolean", default: false },
+      "cursor-scm-proxy": { type: "boolean", default: false },
+      "no-schedules": { type: "boolean", default: false },
+      "no-control-plane": { type: "boolean", default: false },
+      "no-playground": { type: "boolean", default: false },
+      "no-docs": { type: "boolean", default: false },
+      url: { type: "string" },
+      prod: { type: "boolean", default: false },
+      message: { type: "string", multiple: true },
+      input: { type: "string" },
+      "messages-file": { type: "string" },
+      "session-id": { type: "string" },
+      session: { type: "string" },
+      resume: { type: "boolean", default: false },
+      "continuation-token": { type: "string" },
+      events: { type: "string" },
+      "no-events": { type: "boolean", default: false },
+      slug: { type: "string" },
+      "timeout-ms": { type: "string" },
+      tag: { type: "string", multiple: true },
+      list: { type: "boolean", default: false },
+      verbose: { type: "boolean", default: false },
+      text: { type: "boolean", default: false },
+      "no-color": { type: "boolean", default: false },
+      "no-stream": { type: "boolean", default: false },
+      once: { type: "boolean", default: false },
+      "raw-events": { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      name: { type: "string" },
+      env: { type: "string" },
+      "public-url": { type: "string" },
+      "cloud-tools-url": { type: "string" },
+      "mount-path": { type: "string" },
+      "base-url": { type: "string" },
+      print: { type: "boolean", default: false },
+      store: { type: "boolean", default: false },
+      remote: { type: "boolean", default: false },
+      transport: { type: "string" },
+      prefix: { type: "string" },
+      "no-prefix": { type: "boolean", default: false },
+      "channel-posts": { type: "boolean", default: false },
+      "slack-team": { type: "string" },
+      icon: { type: "string" },
+      force: { type: "boolean", default: false },
+      manual: { type: "boolean", default: false },
+      repo: { type: "string", multiple: true },
+      org: { type: "string" },
+      "cursor-events": { type: "boolean", default: false },
+      secret: { type: "string" },
+      channel: { type: "string", multiple: true },
+      install: { type: "boolean", default: false },
+      "no-install": { type: "boolean", default: false },
+      action: { type: "string" },
+      conclusion: { type: "string" },
+      context: { type: "string" },
+      comment: { type: "string" },
+      "dry-run": { type: "boolean", default: false },
+      "as-of": { type: "string" },
+      component: { type: "string" },
+      out: { type: "string" },
+      team: { type: "string" },
+      "no-wait": { type: "boolean", default: false },
+      "cancel-runs": { type: "boolean", default: false },
+      ref: { type: "string" },
+      release: { type: "string" },
+      path: { type: "string" },
+      all: { type: "boolean", default: false },
+      "cursor-events-repo": { type: "string", multiple: true },
+      "allow-domain": { type: "string", multiple: true },
+      // Hidden Anysphere-only flag; omitted from help.
+      "multi-tenant": { type: "boolean", default: false },
+      "from-argv": { type: "boolean", default: false },
+      strict: { type: "boolean", default: false },
+      junit: { type: "string" },
+      artifacts: { type: "string" },
+      "no-artifacts": { type: "boolean", default: false },
+      "skip-report": { type: "boolean", default: false },
+      "max-concurrency": { type: "string" },
+      version: { type: "boolean", short: "V", default: false },
+    },
+  });
+  const dir = values.dir ?? ".";
+  if (values.version === true) {
+    await writeStdout(formatCliVersion({ json: values.json === true }));
+    return 0;
+  }
+
+  // Best-effort, cached, and silent on failure. `update` does its own fresh
+  // lookup, --json runs stay quiet for machine consumers, and `mcp` skips it
+  // so MCP client spawns stay fast (stdout there is the protocol wire).
+  if (
+    command !== "update" &&
+    command !== "mcp" &&
+    values.json !== true &&
+    !isServeRestartWorker()
+  ) {
+    await warnIfOutdated();
+  }
+
+  switch (command) {
+    case "slack": {
+      const { cmdSlack } = await import("../internal/cli-slack.js");
+      const env =
+        values.env === "dev" || values.env === "prod" || values.env === "both"
+          ? values.env
+          : undefined;
+      return cmdSlack(positionals[0], {
+        dir,
+        name: values.name,
+        env,
+        json: values.json,
+        print: values.print,
+        prefix: values.prefix,
+        noPrefix: values["no-prefix"],
+        channelPosts: values["channel-posts"],
+        channels: values.channel,
+        slackTeam: values["slack-team"],
+        prod: values.prod,
+        team: values.team,
+        apiKey: values["api-key"],
+        icon: values.icon,
+        force: values.force,
+        manual: values.manual,
+        install: values.install,
+        noInstall: values["no-install"],
+        iconSource: positionals[0] === "icon" ? positionals[1] : undefined,
+      });
+    }
+    case "github": {
+      const port = values.port === undefined ? undefined : Number.parseInt(values.port, 10);
+      if (port !== undefined && (Number.isNaN(port) || port < 0 || port > 65535)) {
+        process.stderr.write(`invalid --port: ${values.port}\n`);
+        return 1;
+      }
+      const { cmdGithub } = await import("../internal/cli-github.js");
+      return cmdGithub(positionals[0], {
+        dir,
+        slug: values.slug,
+        // `--channel` is repeatable for `slack doctor`; the github
+        // subcommands target a single channel, so the last one wins.
+        channel: values.channel?.at(-1),
+        host: values.host,
+        port,
+        url: values.url,
+        events: values.events,
+        // `--repo` is repeatable for `serve --cursor-events`; the github
+        // subcommands target a single repo, so the last one wins.
+        repo: values.repo?.at(-1),
+        org: values.org,
+        secret: values.secret,
+        install: values.install,
+        json: values.json,
+        prUrl: positionals[1],
+        action: values.action,
+        conclusion: values.conclusion,
+        context: values.context,
+        comment: values.comment,
+        dryRun: values["dry-run"],
+        out: values.out,
+      });
+    }
+    case "gitlab": {
+      const port = values.port === undefined ? undefined : Number.parseInt(values.port, 10);
+      if (port !== undefined && (Number.isNaN(port) || port < 0 || port > 65535)) {
+        process.stderr.write(`invalid --port: ${values.port}\n`);
+        return 1;
+      }
+      const { cmdGitlab } = await import("../internal/cli-gitlab.js");
+      return cmdGitlab(positionals[0], {
+        dir,
+        slug: values.slug,
+        channel: values.channel?.at(-1),
+        host: values.host,
+        port,
+        url: values.url,
+        events: values.events,
+        secret: values.secret,
+        json: values.json,
+        mrUrl: positionals[1],
+        action: values.action,
+        conclusion: values.conclusion,
+        comment: values.comment,
+        dryRun: values["dry-run"],
+        out: values.out,
+      });
+    }
+    case "bitbucket": {
+      const port = values.port === undefined ? undefined : Number.parseInt(values.port, 10);
+      if (port !== undefined && (Number.isNaN(port) || port < 0 || port > 65535)) {
+        process.stderr.write(`invalid --port: ${values.port}\n`);
+        return 1;
+      }
+      const { cmdBitbucket } = await import("../internal/cli-bitbucket.js");
+      return cmdBitbucket(positionals[0], {
+        dir,
+        slug: values.slug,
+        channel: values.channel?.at(-1),
+        host: values.host,
+        port,
+        url: values.url,
+        events: values.events,
+        secret: values.secret,
+        json: values.json,
+        prUrl: positionals[1],
+        comment: values.comment,
+        dryRun: values["dry-run"],
+        out: values.out,
+      });
+    }
+    case "init": {
+      return cmdInit({
+        dir,
+        initTarget: positionals[0],
+        template: values.template,
+        vars: values.var,
+        json: values.json,
+      });
+    }
+
+    case "convert-automation": {
+      const { cmdConvertAutomation } = await import("../internal/cli-convert-automation.js");
+      const dirFlagPassed = rest.includes("--dir") || rest.some(arg => arg.startsWith("--dir="));
+      return cmdConvertAutomation({
+        url: positionals[0],
+        // Default target is ./<automation-name-slug>, not the cwd.
+        dir: dirFlagPassed ? dir : undefined,
+        json: values.json,
+        apiKey: values["api-key"],
+      });
+    }
+
+    case "install-skills": {
+      const { cmdInstallSkills } = await import("../internal/cli-skills.js");
+      return cmdInstallSkills({
+        json: values.json,
+        print: values.print,
+      });
+    }
+
+    case "mcp": {
+      const { cmdMcp } = await import("../internal/cli-mcp.js");
+      const mcpSub = positionals[0];
+      return cmdMcp(mcpSub, {
+        dir,
+        slug: values.slug,
+        team: values.team,
+        apiKey: values["api-key"],
+        url: values.url,
+        prod: values.prod,
+        bearerToken: values["bearer-token"],
+        name: values.name,
+        print: values.print,
+        json: values.json,
+        store: values.store,
+        remote: values.remote,
+        oauthConnection: mcpSub === "oauth" ? positionals[1] : undefined,
+      });
+    }
+
+    case "login": {
+      const { cmdLogin } = await import("../internal/cli-cursor.js");
+      return cmdLogin({
+        apiKey: values["api-key"],
+        keyName: values["key-name"],
+      });
+    }
+
+    case "logout": {
+      const { cmdLogout } = await import("../internal/cli-cursor.js");
+      return cmdLogout();
+    }
+
+    case "whoami": {
+      const { cmdWhoami } = await import("../internal/cli-cursor.js");
+      return cmdWhoami({ json: values.json });
+    }
+
+    case "update": {
+      return cmdUpdate();
+    }
+
+    case "deploy": {
+      // `--repo` is repeatable for `serve --cursor-events`; deploy targets a
+      // single source repo, so the last one wins.
+      const repo = values.repo?.at(-1);
+      return cmdDeploy({
+        ...deployOptionsFromValues(values),
+        dir,
+        ...(values.slug === undefined ? {} : { slug: values.slug }),
+        all: values.all === true,
+        ...(repo === undefined ? {} : { repo }),
+        ...(values.ref === undefined ? {} : { ref: values.ref }),
+        ...(values.path === undefined ? {} : { path: values.path }),
+        ...(values["cursor-events-repo"] === undefined
+          ? {}
+          : { cursorEventsRepos: values["cursor-events-repo"] }),
+        ...(values["allow-domain"] === undefined ? {} : { allowDomains: values["allow-domain"] }),
+        multiTenant: values["multi-tenant"] === true,
+      });
+    }
+
+    case "manifest": {
+      // Offline extraction of deploy metadata (events, egress, routes,
+      // /v1/info payload) — no VM, no network. Wd-1 of the event-ingress
+      // plan; `deploy` attaches this to the request from Wd-2 on.
+      return cmdManifest({ dir, json: values.json === true });
+    }
+
+    case "deployments": {
+      return cmdDeployments(deployOptionsFromValues(values));
+    }
+
+    case "deployment": {
+      return cmdDeploymentStatus(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "stop": {
+      return cmdStop(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "kill": {
+      return cmdKill(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "unlock-deploys": {
+      return cmdUnlockDeploys(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "start": {
+      return cmdStart(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "cancel-runs": {
+      return cmdCancelRuns(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "event-repos": {
+      return cmdEventRepos(positionals[0], values.repo ?? [], deployOptionsFromValues(values));
+    }
+
+    case "upgrade": {
+      return cmdUpgrade(
+        { slug: positionals[0], release: values.release },
+        deployOptionsFromValues(values),
+      );
+    }
+
+    case "delete": {
+      return cmdDelete(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "rotate-token": {
+      return cmdRotateToken(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "secrets": {
+      const base = deployOptionsFromValues(values);
+      switch (positionals[0]) {
+        case "set":
+          return cmdSecretsSet(positionals[1], positionals.slice(2), base);
+        case "list":
+          return cmdSecretsList(positionals[1], base);
+        case "unset":
+          return cmdSecretsUnset(positionals[1], positionals[2], base);
+        default:
+          process.stderr.write(
+            `Usage: ${CLI} secrets <set|list|unset> <slug> ... [--team <id>] [--json]\n`,
+          );
+          return 1;
+      }
+    }
+
+    case "images": {
+      const base = deployOptionsFromValues(values);
+      switch (positionals[0]) {
+        case "push":
+          return cmdImagesPush({ image: positionals[1], name: values.name }, base);
+        case "list":
+          return cmdImagesList(base);
+        case "rm":
+          return cmdImagesRm(positionals[1], base);
+        default:
+          process.stderr.write(
+            `Usage: ${CLI} images <push <local-image> --name <name>|list|rm <name>> [--team <id>] [--json]\n`,
+          );
+          return 1;
+      }
+    }
+
+    case "run": {
+      const messages = await loadMessages(values.message, values["messages-file"]);
+      return cmdRun(
+        axFromOptions({
+          dir,
+          messages,
+          sessionId: values["session-id"] ?? values.session,
+          continuationToken: values["continuation-token"],
+          events: values["no-events"] ? false : values.events === undefined ? true : values.events,
+          text: values.text,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          stateRoot: values["state-root"],
+          timeoutMs: parseTimeoutMs(values["timeout-ms"]),
+          stream: values["no-stream"] ? false : undefined,
+          dryRun: values["dry-run"],
+          asOf: values["as-of"],
+          componentKey: values.component,
+        }),
+      );
+    }
+
+    case "call": {
+      return cmdCall(
+        axFromOptions({
+          dir,
+          toolName: positionals[0],
+          toolInput: values.input,
+          sessionId: values["session-id"] ?? values.session,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          stateRoot: values["state-root"],
+        }),
+      );
+    }
+
+    case "skill": {
+      return cmdSkill(
+        positionals[0],
+        axFromOptions({
+          dir,
+          text: values.text,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          stateRoot: values["state-root"],
+        }),
+      );
+    }
+
+    case "trajectory": {
+      if (values.events === undefined) {
+        process.stderr.write("trajectory requires --events <file.ndjson>\n");
+        return 1;
+      }
+      return cmdTrajectory(
+        axFromOptions({
+          dir,
+          events: values.events,
+          text: values.text,
+        }),
+      );
+    }
+
+    case "eval": {
+      // Remote status subcommand only when targeting --prod/--url. Otherwise
+      // the bare token "status" is a normal eval id (evals/status.eval.ts).
+      if (positionals[0] === "status" && (values.prod === true || values.url !== undefined)) {
+        return cmdEvalStatus(
+          positionals[1],
+          axFromOptions({
+            dir,
+            json: values.json,
+            url: values.url,
+            prod: values.prod,
+            team: values.team,
+            apiKey: values["api-key"],
+            slug: values.slug,
+            bearerToken: values["bearer-token"],
+            out: values.out,
+          }),
+        );
+      }
+      if (positionals[0] === "cancel" && (values.prod === true || values.url !== undefined)) {
+        return cmdEvalCancel(
+          positionals[1],
+          axFromOptions({
+            dir,
+            json: values.json,
+            url: values.url,
+            prod: values.prod,
+            team: values.team,
+            apiKey: values["api-key"],
+            slug: values.slug,
+            bearerToken: values["bearer-token"],
+          }),
+        );
+      }
+      return cmdEval(
+        axFromOptions({
+          dir,
+          evalIds: positionals,
+          list: values.list,
+          verbose: values.verbose,
+          json: values.json,
+          tags: values.tag,
+          url: values.url,
+          prod: values.prod,
+          noWait: values["no-wait"],
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          stateRoot: values["state-root"],
+          timeoutMs: parseTimeoutMs(values["timeout-ms"]),
+          stream: values["no-stream"] ? false : undefined,
+          strict: values.strict,
+          junit: values.junit,
+          artifacts: values["no-artifacts"] ? false : values.artifacts,
+          skipReport: values["skip-report"],
+          maxConcurrency: parseMaxConcurrency(values["max-concurrency"]),
+          out: values.out,
+        }),
+      );
+    }
+
+    case "chat": {
+      return cmdChat(
+        axFromOptions({
+          dir,
+          messages: values.message,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          sessionId: values["session-id"] ?? values.session,
+          resume: values.resume,
+          continuationToken: values["continuation-token"],
+          bearerToken: values["bearer-token"],
+          json: values.json,
+          text: values.text,
+          noColor: values["no-color"],
+        }),
+      );
+    }
+
+    case "resume": {
+      return cmdResume(
+        positionals[0],
+        axFromOptions({
+          dir,
+          messages: values.message,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          // Positional wins; --session is accepted as a redundant alias.
+          // No id → resume previous (cmdResume sets resume: true).
+          sessionId: positionals[0] ?? values["session-id"] ?? values.session,
+          continuationToken: values["continuation-token"],
+          bearerToken: values["bearer-token"],
+          json: values.json,
+          text: values.text,
+          noColor: values["no-color"],
+        }),
+      );
+    }
+
+    case "logs": {
+      return cmdLogs(
+        axFromOptions({
+          dir,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          json: values.json,
+          once: values.once,
+        }),
+      );
+    }
+
+    case "sessions": {
+      return cmdSessions(
+        axFromOptions({
+          dir,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          json: values.json,
+        }),
+      );
+    }
+
+    case "session": {
+      const messages = await loadMessages(values.message, values["messages-file"]);
+      return cmdSession(
+        positionals[0],
+        axFromOptions({
+          dir,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          json: values.json,
+          text: values.text,
+          rawEvents: values["raw-events"],
+          out: values.out,
+          messages,
+          sessionId: values["session-id"] ?? values.session,
+          dryRun: values["dry-run"],
+          asOf: values["as-of"],
+          componentKey: values.component,
+        }),
+      );
+    }
+
+    case "cost": {
+      return cmdCost(
+        positionals[0] ?? values["session-id"] ?? values.session,
+        axFromOptions({
+          dir,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          json: values.json,
+        }),
+      );
+    }
+
+    case "playground": {
+      return cmdPlayground(
+        axFromOptions({
+          dir,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          sessionId: values["session-id"] ?? values.session,
+          print: values.print,
+        }),
+      );
+    }
+
+    case "docs": {
+      const docsPort = values.port === undefined ? 0 : Number.parseInt(values.port, 10);
+      if (Number.isNaN(docsPort) || docsPort < 0 || docsPort > 65535) {
+        process.stderr.write(`invalid --port: ${values.port}\n`);
+        return 1;
+      }
+      const { cmdDocs } = await import("../internal/cli-docs.js");
+      return cmdDocs({
+        port: docsPort,
+        host: values.host,
+        print: values.print === true,
+      });
+    }
+
+    case "validate": {
+      const mounts = await loadMounts(dir);
+      let hasError = false;
+      for (const { slug, project } of mounts) {
+        const label = slug === "" ? project.name : `${slug} (${project.name})`;
+        if (project.diagnostics.length === 0) {
+          process.stdout.write(`ok: ${label} has no diagnostics\n`);
+          continue;
+        }
+        process.stdout.write(`${label}:\n${formatDiagnostics(project.diagnostics)}\n`);
+        hasError ||= project.diagnostics.some(d => d.severity === "error");
+      }
+      return hasError ? 1 : 0;
+    }
+
+    case "info": {
+      const mounts = await loadMounts(dir);
+      if (values.json) {
+        const payload =
+          mounts.length === 1 && mounts[0]?.slug === ""
+            ? projectInfo(mounts[0].project)
+            : {
+                agents: mounts.map(({ slug, project }) => ({
+                  slug,
+                  ...projectInfo(project),
+                })),
+              };
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return 0;
+      }
+      if (mounts.length > 1 || mounts[0]?.slug !== "") {
+        process.stdout.write(`${mounts.length} agents under ${dir}:\n\n`);
+        for (const { slug, project } of mounts) {
+          const info = projectInfo(project);
+          process.stdout.write(
+            `  /${slug}  —  ${info.name}  (${formatModel(info.model)}, ${info.tools.length} tools, ${info.channels.length} channels)\n`,
+          );
+        }
+        const anyError = mounts.some(m => m.project.diagnostics.some(d => d.severity === "error"));
+        return anyError ? 1 : 0;
+      }
+      const project = mounts[0]?.project as AgentProject;
+      const info = projectInfo(project);
+      const lines: string[] = [];
+      lines.push(`agent: ${info.name}`);
+      lines.push(`model: ${formatModel(info.model)}`);
+      lines.push(`mcp: ${info.mcp.path} (${info.mcp.tools.join(", ")})`);
+      if (info.instructions !== undefined) {
+        lines.push(`instructions: ${info.instructions.chars} chars`);
+      }
+      lines.push(
+        section(
+          "tools",
+          info.tools.map(t => `${t.name} — ${t.description}`),
+        ),
+      );
+      lines.push(
+        section(
+          "skills",
+          info.skills.map(s => `${s.name} — ${s.description}`),
+        ),
+      );
+      lines.push(
+        section(
+          "extensions",
+          info.extensions.map(
+            e => `${e.name} — ${[...e.tools, ...e.skills].join(", ") || "(nothing contributed)"}`,
+          ),
+        ),
+      );
+      lines.push(
+        section(
+          "MCP connections",
+          info.connections.map(c => `${c.name} — ${c.transport}`),
+        ),
+      );
+      lines.push(
+        section(
+          "subagents",
+          info.subagents.map(s => `${s.name} — ${s.description ?? ""}`),
+        ),
+      );
+      lines.push(
+        section(
+          "channels",
+          info.channels.map(
+            c =>
+              `${c.id}: ${c.routes.map(r => `${r.method} ${r.url}`).join(", ") || "(events only)"}`,
+          ),
+        ),
+      );
+      lines.push(
+        section(
+          "schedules",
+          info.schedules.map(s => `${s.name} (${s.cron}, ${s.kind})`),
+        ),
+      );
+      lines.push(section("hooks", info.hooks));
+      lines.push(section("hosting egress domains", info.hosting?.egressDomains ?? []));
+      lines.push(section("hosting secret names", info.hosting?.secretNames ?? []));
+      if (info.diagnostics.length > 0) {
+        lines.push(`\ndiagnostics:\n${formatDiagnostics(info.diagnostics)}`);
+      }
+      process.stdout.write(`${lines.filter(line => line !== "").join("\n")}\n`);
+      return info.diagnostics.some(d => d.severity === "error") ? 1 : 0;
+    }
+
+    case "dev":
+    case "serve": {
+      const serveDirResult = resolveServeDir({
+        command,
+        dir,
+        positionals,
+        dirFlagPassed: rest.includes("--dir"),
+      });
+      if (typeof serveDirResult !== "string") {
+        process.stderr.write(serveDirResult.error);
+        return 1;
+      }
+      const serveDir = serveDirResult;
+      const port = values.port === undefined ? undefined : Number.parseInt(values.port, 10);
+      if (port !== undefined && (Number.isNaN(port) || port < 0 || port > 65535)) {
+        process.stderr.write(`invalid --port: ${values.port}\n`);
+        return 1;
+      }
+      if (values["allow-anonymous"] === true && values["bearer-token"] !== undefined) {
+        process.stderr.write("--allow-anonymous and --bearer-token are mutually exclusive\n");
+        return 1;
+      }
+      const mode = values.mode;
+      if (mode !== undefined && mode !== "single" && mode !== "multi") {
+        process.stderr.write(`invalid --mode: ${mode} (expected "single" or "multi")\n`);
+        return 1;
+      }
+      const dev = command === "dev" || values.dev === true;
+      const style = stdoutPalette();
+      // Real env wins (loadEnvFile never overrides). Runs inside start()
+      // so dev's Enter-restart picks up tokens written since boot.
+      const loadLocalEnv = (): void => {
+        const loadedEnvFiles = loadAgentLocalEnv(serveDir);
+        if (loadedEnvFiles.length > 0) {
+          process.stdout.write(`${style.dim(`env: loaded ${loadedEnvFiles.join(", ")}`)}\n`);
+        }
+      };
+      const serveOptions = {
+        port,
+        host: values.host,
+        mode: mode as "single" | "multi" | undefined,
+        dev,
+        apiKey: values["api-key"],
+        stateRoot: values["state-root"],
+        authToken: values["bearer-token"],
+        allowAnonymous: values["allow-anonymous"] === true ? true : undefined,
+        allowAnonymousCursorGithub:
+          values["allow-anonymous-cursor-github"] === true ? true : undefined,
+        allowAnonymousCursorAccountMcp:
+          values["allow-anonymous-cursor-account-mcp"] === true ? true : undefined,
+        allowAnonymousGrokbot: values["allow-anonymous-grokbot"] === true ? true : undefined,
+        cursorScmProxy: values["cursor-scm-proxy"] === true ? true : undefined,
+        schedules: values["no-schedules"] === true ? false : undefined,
+        noControlPlane: values["no-control-plane"] === true ? true : undefined,
+        playground: values["no-playground"] === true ? false : undefined,
+        docs: values["no-docs"] === true ? false : undefined,
+        publicUrl: values["public-url"],
+        cloudToolsUrl: values["cloud-tools-url"],
+        cursorEvents: values["cursor-events"] === true ? { repos: values.repo ?? [] } : undefined,
+        // Soft boot logs stay secondary to the banner. `dim` is a no-op on
+        // already-styled lines (the MCP warning box).
+        logger: (line: string) => {
+          process.stdout.write(`${style.dim(line)}\n`);
+        },
+      };
+      const enterToRestart = process.stdin.isTTY === true;
+      if (enterToRestart && !isServeRestartWorker()) {
+        return runEnterRestartSupervisor({
+          spawn: (command, args, spawnOptions) => spawn(command, args, spawnOptions),
+          onRestart: () => {
+            clearTerminal();
+          },
+        });
+      }
+
+      const bannerOpts = {
+        noPlayground: values["no-playground"] === true,
+        dev,
+        bearerToken: values["bearer-token"] !== undefined,
+        noSchedules: values["no-schedules"] === true,
+      };
+
+      const start = async (): Promise<AgentServeHandle> => {
+        loadLocalEnv();
+        const next = await serve(serveDir, serveOptions);
+        printServeBanner(next, bannerOpts);
+        if (enterToRestart) {
+          process.stdout.write(style.dim("  press Enter to restart\n"));
+        }
+        return next;
+      };
+
+      const handle = await start();
+      let closing = false;
+      let restartRequested = false;
+
+      await new Promise<void>(resolve => {
+        const shutdown = (): void => {
+          if (closing) {
+            return;
+          }
+          closing = true;
+          process.stdout.write("\nshutting down (draining running turns)\n");
+          void handle.close().finally(resolve);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+
+        if (!enterToRestart) {
+          return;
+        }
+
+        process.stdin.resume();
+        process.stdin.on("data", (chunk: string | Buffer) => {
+          const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+          if (!isEnterOnly(text) || closing) {
+            return;
+          }
+          closing = true;
+          restartRequested = true;
+          clearTerminal();
+          process.stdout.write(style.dim("restarting…\n"));
+          void handle.close().finally(resolve);
+        });
+      });
+      return restartRequested ? ENTER_RESTART_EXIT_CODE : 0;
+    }
+
+    default: {
+      process.stderr.write(`Unknown command "${command}"\n\n${HELP}`);
+      return 1;
+    }
+  }
+}
+
+function deployOptionsFromValues(values: {
+  team?: string;
+  json?: boolean;
+  "no-wait"?: boolean;
+  "cancel-runs"?: boolean;
+  channel?: string[];
+  "api-key"?: string;
+  "from-argv"?: boolean;
+}): DeployCliOptions {
+  return {
+    team: values.team,
+    json: values.json === true,
+    noWait: values["no-wait"] === true,
+    cancelRuns: values["cancel-runs"] === true,
+    apiKey: values["api-key"],
+    fromArgv: values["from-argv"] === true ? true : undefined,
+  };
+}
+
+function axFromOptions(partial: Partial<AxCliOptions> & { dir: string }): AxCliOptions {
+  return {
+    dir: partial.dir,
+    cwd: partial.cwd,
+    slug: partial.slug,
+    bearerToken: partial.bearerToken,
+    stateRoot: partial.stateRoot,
+    messages: partial.messages,
+    sessionId: partial.sessionId,
+    resume: partial.resume,
+    continuationToken: partial.continuationToken,
+    dryRun: partial.dryRun,
+    asOf: partial.asOf,
+    componentKey: partial.componentKey,
+    timeoutMs: partial.timeoutMs,
+    events: partial.events,
+    text: partial.text,
+    json: partial.json,
+    list: partial.list,
+    verbose: partial.verbose,
+    tags: partial.tags,
+    evalIds: partial.evalIds,
+    initTarget: partial.initTarget,
+    vars: partial.vars,
+    toolName: partial.toolName,
+    toolInput: partial.toolInput,
+    url: partial.url,
+    prod: partial.prod,
+    noWait: partial.noWait,
+    team: partial.team,
+    apiKey: partial.apiKey,
+    fetchImpl: partial.fetchImpl,
+    stream: partial.stream,
+    noColor: partial.noColor,
+    once: partial.once,
+    rawEvents: partial.rawEvents,
+    print: partial.print,
+    strict: partial.strict,
+    junit: partial.junit,
+    artifacts: partial.artifacts,
+    skipReport: partial.skipReport,
+    maxConcurrency: partial.maxConcurrency,
+    out: partial.out,
+  };
+}
+
+async function loadMessages(
+  messages: string[] | undefined,
+  messagesFile: string | undefined,
+): Promise<string[]> {
+  const out: string[] = [];
+  if (messagesFile !== undefined) {
+    const raw = await readFile(resolve(messagesFile), "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) {
+      throw new Error("--messages-file must be a JSON array of strings");
+    }
+    for (const item of parsed) {
+      if (typeof item !== "string") {
+        throw new Error("--messages-file entries must be strings");
+      }
+      out.push(item);
+    }
+  }
+  if (messages !== undefined) {
+    out.push(...messages);
+  }
+  return out;
+}
+
+function parseTimeoutMs(value: string | undefined): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const n = Number.parseInt(value, 10);
+  if (Number.isNaN(n) || n <= 0) {
+    throw new Error(`invalid --timeout-ms: ${value}`);
+  }
+  return n;
+}
+
+function parseMaxConcurrency(value: string | undefined): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const n = Number.parseInt(value, 10);
+  if (Number.isNaN(n) || n <= 0) {
+    throw new Error(`invalid --max-concurrency: ${value}`);
+  }
+  return n;
+}
+
+/**
+ * Load mounts the same way `serve` does (multi-agent layout by default).
+ */
+async function loadMounts(dir: string): Promise<Array<{ slug: string; project: AgentProject }>> {
+  return resolveAgentMounts(dir);
+}
+
+function section(title: string, items: string[]): string {
+  if (items.length === 0) {
+    return "";
+  }
+  return `${title}:\n${items.map(item => `  - ${item}`).join("\n")}`;
+}
+
+function isEnterOnly(text: string): boolean {
+  return text.length > 0 && [...text].every(ch => ch === "\n" || ch === "\r");
+}
+
+/**
+ * `dev [path]` takes a positional project root; `serve` keeps `--dir` only.
+ * Reject mixing a positional with an explicit `--dir`, and extra args on `dev`.
+ */
+function resolveServeDir(args: {
+  command: string;
+  dir: string;
+  positionals: string[];
+  dirFlagPassed: boolean;
+}): string | { error: string } {
+  if (args.command !== "dev") {
+    return args.dir;
+  }
+  if (args.positionals.length > 1) {
+    return {
+      error: `${CLI} dev: unexpected arguments: ${args.positionals.slice(1).join(" ")}\n`,
+    };
+  }
+  const positionalDir = args.positionals[0];
+  if (positionalDir === undefined) {
+    return args.dir;
+  }
+  if (args.dirFlagPassed && args.dir !== positionalDir) {
+    return {
+      error: `${CLI} dev: pass a path as a positional or --dir, not both\n`,
+    };
+  }
+  return positionalDir;
+}
+
+function printServeBanner(
+  handle: AgentServeHandle,
+  opts: {
+    noPlayground: boolean;
+    dev: boolean;
+    bearerToken: boolean;
+    noSchedules: boolean;
+  },
+): void {
+  const c = stdoutPalette();
+  const agents = handle.agents;
+  // Name the framework build in the boot line: hosted engines install the
+  // published package at provision time, so the serve log is the only
+  // durable record of which build a deployment's turns actually ran on.
+  const versionTag = c.dim(`(${PACKAGE_NAME} ${packageVersion()})`);
+  if (agents.length > 1) {
+    process.stdout.write(`${agents.length} agents listening ${versionTag}\n`);
+  } else {
+    const info = projectInfo(agents[0]?.project ?? handle.project);
+    process.stdout.write(`${info.name} listening ${versionTag}\n`);
+  }
+
+  const playgroundUrl = resolvePlaygroundBannerUrl(handle, opts.noPlayground);
+  if (playgroundUrl !== undefined) {
+    process.stdout.write(`  playground  ${c.cyan(playgroundUrl)}\n`);
+  }
+  // `/` is only mounted when the playground host home is enabled.
+  if (!opts.noPlayground) {
+    process.stdout.write(`  home        ${c.cyan(`${handle.url}/`)}\n`);
+  }
+  // Dev is playground-first (Vite proxies the API). Keep API/route detail for
+  // plain `serve`, where operators often curl the HTTP surface directly.
+  if (!opts.dev) {
+    process.stdout.write(c.dim(`  api  ${handle.url}\n`));
+    if (agents.length > 1 || agents[0]?.slug !== "") {
+      for (const agent of agents) {
+        const info = projectInfo(agent.project);
+        process.stdout.write(c.dim(`  /${agent.slug}  ${info.name}\n`));
+      }
+    } else {
+      const info = projectInfo(handle.project);
+      process.stdout.write(c.dim(`  POST ${handle.url}/v1/session\n`));
+      process.stdout.write(c.dim(`  GET  ${handle.url}/v1/session/:sessionId/stream\n`));
+      for (const channel of info.channels) {
+        if (channel.id === "http") {
+          continue;
+        }
+        for (const route of channel.routes) {
+          process.stdout.write(c.dim(`  ${route.method} ${handle.url}${route.url}\n`));
+        }
+      }
+      if (info.schedules.length > 0) {
+        const scheduleMode = opts.noSchedules ? "disabled" : "running on cron cadence (UTC)";
+        process.stdout.write(
+          c.dim(`  schedules: ${info.schedules.map(s => s.name).join(", ")} — ${scheduleMode}\n`),
+        );
+      }
+    }
+    if (handle.docsUrl !== undefined) {
+      process.stdout.write(c.dim(`  docs  ${handle.docsUrl}\n`));
+    }
+  }
+
+  if (opts.bearerToken) {
+    process.stdout.write(
+      c.dim("  auth: bearer token required on API routes (playground has a token field)\n"),
+    );
+  }
+  if (
+    opts.dev &&
+    (process.env.GITHUB_WEBHOOK_SECRET === undefined || process.env.GITHUB_WEBHOOK_SECRET === "") &&
+    handle.agents.some(agent => projectInfo(agent.project).channels.some(c => c.kind === "github"))
+  ) {
+    process.stdout.write(
+      c.dim(
+        `  github: dev accepts unsigned loopback deliveries (${CLI} github forward works without a secret; set GITHUB_WEBHOOK_SECRET to verify signatures)\n`,
+      ),
+    );
+  }
+  if (
+    opts.dev &&
+    (process.env.GITLAB_WEBHOOK_SECRET === undefined || process.env.GITLAB_WEBHOOK_SECRET === "") &&
+    handle.agents.some(agent => projectInfo(agent.project).channels.some(c => c.kind === "gitlab"))
+  ) {
+    process.stdout.write(
+      c.dim(
+        `  gitlab: dev accepts unsigned loopback deliveries (${CLI} gitlab replay works without a secret; set GITLAB_WEBHOOK_SECRET to verify X-Gitlab-Token)\n`,
+      ),
+    );
+  }
+  if (
+    opts.dev &&
+    (process.env.BITBUCKET_WEBHOOK_SECRET === undefined ||
+      process.env.BITBUCKET_WEBHOOK_SECRET === "") &&
+    handle.agents.some(agent =>
+      projectInfo(agent.project).channels.some(c => c.kind === "bitbucket"),
+    )
+  ) {
+    process.stdout.write(
+      c.dim(
+        `  bitbucket: dev accepts unsigned loopback deliveries (${CLI} bitbucket replay works without a secret; set BITBUCKET_WEBHOOK_SECRET to verify X-Hub-Signature)\n`,
+      ),
+    );
+  }
+}
+
+/** Prefer the Vite playground URL in --dev; otherwise the static SPA path. */
+function resolvePlaygroundBannerUrl(
+  handle: AgentServeHandle,
+  noPlayground: boolean,
+): string | undefined {
+  if (noPlayground) {
+    return undefined;
+  }
+  if (handle.playgroundDevUrl !== undefined) {
+    return handle.playgroundDevUrl.replace(/\/$/, "");
+  }
+  if (handle.agents.length === 1) {
+    return `${handle.agents[0]!.url}/playground`;
+  }
+  if (handle.agents.length > 1) {
+    return handle.url;
+  }
+  return undefined;
+}
+
+function formatModel(model: unknown): string {
+  if (model === undefined) {
+    return "(unset)";
+  }
+  if (typeof model === "string") {
+    return model;
+  }
+  return JSON.stringify(model);
+}
+
+/**
+ * The Cursor SDK's Connect/HTTP2 client sometimes emits uncaught stream
+ * or TLS errors (notably `NGHTTP2_FRAME_SIZE_ERROR` on large shell/tool
+ * payloads, and mid-handshake socket disconnects) outside the promise
+ * `run.wait()` returns. Without a listener the unhandled rejection exits
+ * the whole agent-serve process with code 1. Swallow those transport
+ * failures so turns can fail cleanly and the server stays up.
+ */
+function installTransportErrorGuards(): void {
+  const isTransportNoise = (reason: unknown): boolean => {
+    const message =
+      reason instanceof Error ? `${reason.message}\n${reason.stack ?? ""}` : String(reason);
+    const code =
+      reason !== null &&
+      typeof reason === "object" &&
+      "code" in reason &&
+      typeof (reason as { code: unknown }).code === "string"
+        ? (reason as { code: string }).code
+        : undefined;
+    return (
+      code === "ERR_HTTP2_STREAM_ERROR" ||
+      code === "ECONNRESET" ||
+      code === "ECONNREFUSED" ||
+      code === "EPIPE" ||
+      code === "ETIMEDOUT" ||
+      code === "ENOTFOUND" ||
+      code === "EAI_AGAIN" ||
+      message.includes("NGHTTP2_FRAME_SIZE_ERROR") ||
+      message.includes("Stream closed with error code") ||
+      message.includes(
+        "Client network socket disconnected before secure TLS connection was established",
+      ) ||
+      message.includes("socket hang up") ||
+      message.includes("other side closed")
+    );
+  };
+  const log = (label: string, reason: unknown): void => {
+    const text = reason instanceof Error ? reason.message : String(reason);
+    process.stderr.write(`[agent-sdk] ${label} (server stays up): ${text.slice(0, 400)}\n`);
+  };
+  process.on("unhandledRejection", reason => {
+    if (isTransportNoise(reason)) {
+      log("swallowed unhandledRejection", reason);
+      return;
+    }
+    log("unhandledRejection", reason);
+  });
+  process.on("uncaughtException", error => {
+    if (isTransportNoise(error)) {
+      log("swallowed uncaughtException", error);
+      return;
+    }
+    process.stderr.write(`[agent-sdk] uncaughtException: ${error.stack ?? error.message}\n`);
+    void flushSessionRunFatal(error).finally(() => {
+      process.exit(1);
+    });
+  });
+}
+
+installTransportErrorGuards();
+
+// Authored agent files are TypeScript imported at runtime; install the tsx
+// loader (and the framework import aliases on compiled runs) before any
+// command touches a project. In-repo CLI is `bin/agent-serve.ts`.
+registerAuthoredModuleLoaders()
+  .then(() => main(process.argv.slice(2)))
+  .then(
+    code => {
+      // Ephemeral run/eval can leave SDK/HTTP handles open; force exit.
+      process.exit(code);
+    },
+    error => {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exit(1);
+    },
+  );