@cursor/bdk 0.2.2 → 0.2.4

package/src/bin/agent-serve.ts

@@ -1,1833 +0,0 @@
-#!/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);
-    },
-  );