@cursor/july 0.1.2 → 0.1.3

package/dist/bin/agent-serve.js

@@ -3,10 +3,12 @@
  * agent-serve CLI.
  *
  *   agent-serve serve      [--dir .] [--port 3000] [--host 127.0.0.1] [--dev]
+ *   agent-serve dev        [path] [--port 3000] [--host 127.0.0.1]
  *   agent-serve chat      [--url http://127.0.0.1:3000] [--message "..."] [--json]
+ *   agent-serve resume    <sessionId> [--url | --prod] [--message "..."]
  *   agent-serve run       [--dir .] [--message "..."] [--json|--text]
  *   agent-serve trajectory --events <file.ndjson>
- *   agent-serve init      [dir]
+ *   agent-serve init      [dir] [--json]
  *   agent-serve eval        [--dir .] [evalId...]
  *   agent-serve validate   [--dir .]
  *   agent-serve slack     <subcommand>
@@ -25,12 +27,10 @@ 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 { runChat } from "../internal/chat-client.js";
-import { cmdCall, cmdEval, cmdInit, cmdRun, cmdTrajectory, } from "../internal/cli-ax.js";
+import { cmdCall, cmdChat, cmdEval, cmdInit, cmdLogs, cmdPlayground, cmdResume, cmdRun, cmdSession, cmdSessions, cmdTrajectory, } from "../internal/cli-ax.js";
 import { cmdDeploy, cmdDeploymentStatus, cmdDeployments, cmdRotatePodCredential, cmdRotateToken, cmdSecretsList, cmdSecretsSet, cmdSecretsUnset, cmdStop, } from "../internal/cli-deploy.js";
 import { CLI_COMMAND_NAME as CLI } from "../internal/distribution.js";
-import { runSession } from "../internal/run-client.js";
-import { formatTrajectoryText } from "../internal/trajectory.js";
+import { clearTerminal, stdoutPalette } from "../internal/terminal-style.js";
 const HELP = `${CLI} — serve a filesystem-defined Cursor agent over channels
 
 Usage:
@@ -38,24 +38,42 @@ Usage:
                           [--mode single|multi] [--api-key <key>] [--no-schedules]
                           [--public-url <url>]
                           [--cursor-events --repo <owner/name>]...
-  ${CLI} chat        [--url <baseUrl>] [--message <text>] [--json] [--text]
-  ${CLI} run         [--dir <path>] [--message <text>]... [--url <baseUrl>]
+  ${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>] [--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]
+                          [--slug <slug>] [--team <id>] [--dir <path>]
+  ${CLI} playground  [--url <baseUrl> | --prod] [--session <id>] [--print]
+                          [--slug <slug>] [--team <id>] [--dir <path>]
+  ${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]
+                          [--timeout-ms <n>] [--no-stream] [--slug <slug>] [--team <id>]
   ${CLI} trajectory  --events <file.ndjson> [--text]
-  ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl>]
-                          [--session <id>] [--slug <slug>]
-  ${CLI} init        [dir]
+  ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
+                          [--session <id>] [--slug <slug>] [--team <id>]
+  ${CLI} init        [dir] [--json]
   ${CLI} eval        [--dir <path>] [evalId...] [--list] [--json]
                           [--tag <tag>]... [--verbose] [--timeout-ms <n>]
-                          [--no-stream]
+                          [--no-stream] [--url <baseUrl> | --prod] [--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} deploy      [--dir <path>] [--slug <slug>] [--team <id>] [--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>]...
@@ -72,15 +90,41 @@ Usage:
 Commands:
   serve       Serve agents under /<slug>/... (index at /). On a TTY, press
               Enter to restart (reloads agent code + Vite HMR child).
-  chat        Talk to a running server (streams the reply). --json prints a trajectory.
+  dev         Local development: same as \`${CLI} serve --dev\` (manual
+              schedule/reminder dispatch, unsigned GitHub loopback, Vite HMR).
+  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. --json is one-shot. Pass --prod to hit the team's
+              hosted deployment (slug from --slug or the directory name).
+  resume      Reattach chat to an existing session id (same as
+              \`${CLI} chat --session <id>\`). 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>\`.
+  playground  Open the web playground. --prod starts a loopback proxy that
+              injects hosted engine credentials (browsers cannot set them).
+              --print skips opening a browser. Ctrl-C stops the proxy.
   run         One-shot create→test loop: ephemeral server + JSON trajectory.
               Writes a single events.ndjson trace (visualize in the playground).
               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.
   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.
-  init        Scaffold a project, or print the coding-agent setup guide (no args).
+  init        Scaffold a project (skipping existing files), npm install,
+              run login when unsigned, then print next steps. --json is
+              machine-readable and never blocks on login. No directory:
+              print the setup guide.
   eval        Run filesystem evals under evals/**/*.eval.ts (streams on a TTY).
               Pass evalId args to select: one datapoint (weather/nyc), a whole
               file (weather → all cases in that file), several of either, or
@@ -93,8 +137,11 @@ Commands:
   logout      Remove the stored Cursor credentials.
   whoami      Show which Cursor account powers this host (and why).
   deploy      Deploy onto Cursor's managed agent-serve hosting, then wait for
-              the engine to come up. First deploy of a slug prints the alias
-              token exactly once — save it.
+              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 a deployment and wait until it reports stopped.
@@ -115,6 +162,7 @@ Agent loop:
   ${CLI} info --dir . --json
   ${CLI} run --dir . --message "..."
   ${CLI} eval --dir .
+  ${CLI} dev .
 
 Options:
   --dir             Project root (defaults to the current directory).
@@ -135,28 +183,49 @@ Options:
                      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).
   --public-url       serve: base URL where this host is reachable from outside
                      (e.g. https://agent-serve.example.com). Required for peer
                      connections (defineConnection({ agent })) on cloud-runtime
                      turns; local turns always use loopback.
   --no-schedules     Disable the cron runner outside dev mode.
-  --team             deploy/deployments/deployment/stop/rotate-token: Cursor
-                     team id. Defaults to the account's team when it has one.
+  --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\`.
+  --once             logs: print current progress / log buffer once and exit
+                     (default is to follow).
+  --print            playground: print the URL only; do not open a browser.
   --no-wait          deploy/stop: return right after the request is accepted
                      instead of polling until a terminal status.
   --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/run/eval: base URL of a running agent (skip local host).
-  --message          chat/run: user message (repeatable for run).
+  --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 for a follow-up turn.
-  --continuation-token  Token from a prior run/chat response.
+  --session          Existing session id (run/call follow-up, or chat reattach).
+                     Prefer \`${CLI} resume <sessionId>\` for interactive
+                     reattach.
+  --continuation-token  Token from a prior run/chat/resume response (optional
+                     for resume / chat --session; 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.
+                     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.
@@ -164,7 +233,9 @@ Options:
   --list             eval: print discovered cases without running.
   --verbose          eval: stream t.log lines and reply snippets.
   --no-stream        run/eval: silence live progress on stderr (JSON still prints).
-  --json             JSON output (info/chat/eval/github; run defaults to JSON).
+  --json             JSON output (init/info/chat/eval/logs/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
@@ -174,10 +245,15 @@ Options:
   --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 the control plane builds from.
-  --ref              deploy: git ref to build (defaults to the repo's default
-                     branch server-side).
-  --path             deploy: agent directory relative to the repo root.
+                     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) whose SCM events the
                      deployed engine pulls (repeatable).
   --allow-domain     deploy: egress domain the engine pod may reach
@@ -198,9 +274,9 @@ Options:
 `;
 function main(argv) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-        var _k, _l, _m, _o, _p, _q, _r, _s;
-        const [command, ...rest] = argv;
+        var _a, _b, _c, _d, _e, _f, _g;
+        var _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
+        const [command, ...restIn] = argv;
         if (command === undefined ||
             command === "help" ||
             command === "--help" ||
@@ -208,6 +284,11 @@ function main(argv) {
             process.stdout.write(HELP);
             return command === undefined ? 1 : 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,
@@ -222,10 +303,12 @@ function main(argv) {
                 "state-root": { type: "string" },
                 "bearer-token": { type: "string" },
                 "allow-anonymous": { type: "boolean", default: false },
+                "allow-anonymous-cursor-github": { type: "boolean", default: false },
                 "no-schedules": { 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" },
@@ -242,6 +325,8 @@ function main(argv) {
                 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" },
@@ -269,11 +354,12 @@ function main(argv) {
                 "no-wait": { type: "boolean", default: false },
                 ref: { type: "string" },
                 path: { type: "string" },
+                all: { type: "boolean", default: false },
                 "cursor-events-repo": { type: "string", multiple: true },
                 "allow-domain": { type: "string", multiple: true },
             },
         });
-        const dir = (_k = values.dir) !== null && _k !== void 0 ? _k : ".";
+        const dir = (_h = values.dir) !== null && _h !== void 0 ? _h : ".";
         switch (command) {
             case "slack": {
                 const { cmdSlack } = yield import("../internal/cli-slack.js");
@@ -329,6 +415,7 @@ function main(argv) {
                 return cmdInit({
                     dir,
                     initTarget: positionals[0],
+                    json: values.json,
                 });
             }
             case "login": {
@@ -350,7 +437,7 @@ function main(argv) {
                 // `--repo` is repeatable for `serve --cursor-events`; deploy targets a
                 // single source repo, so the last one wins.
                 const repo = (_b = values.repo) === null || _b === void 0 ? void 0 : _b.at(-1);
-                return cmdDeploy(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, deployOptionsFromValues(values)), { dir }), (values.slug === undefined ? {} : { slug: values.slug })), (repo === undefined ? {} : { repo })), (values.ref === undefined ? {} : { ref: values.ref })), (values.path === undefined ? {} : { path: values.path })), (values["cursor-events-repo"] === undefined
+                return cmdDeploy(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, 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
                     ? {}
@@ -390,7 +477,7 @@ function main(argv) {
                 return cmdRun(axFromOptions({
                     dir,
                     messages,
-                    sessionId: (_l = values["session-id"]) !== null && _l !== void 0 ? _l : values.session,
+                    sessionId: (_j = values["session-id"]) !== null && _j !== void 0 ? _j : values.session,
                     continuationToken: values["continuation-token"],
                     events: values["no-events"]
                         ? false
@@ -399,6 +486,9 @@ function main(argv) {
                             : 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"],
@@ -411,8 +501,11 @@ function main(argv) {
                     dir,
                     toolName: positionals[0],
                     toolInput: values.input,
-                    sessionId: (_m = values["session-id"]) !== null && _m !== void 0 ? _m : values.session,
+                    sessionId: (_k = values["session-id"]) !== null && _k !== void 0 ? _k : 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"],
@@ -438,6 +531,9 @@ function main(argv) {
                     json: values.json,
                     tags: values.tag,
                     url: values.url,
+                    prod: values.prod,
+                    team: values.team,
+                    apiKey: values["api-key"],
                     slug: values.slug,
                     bearerToken: values["bearer-token"],
                     stateRoot: values["state-root"],
@@ -446,20 +542,91 @@ function main(argv) {
                 }));
             }
             case "chat": {
-                if (values.json) {
-                    return chatJson({
-                        baseUrl: (_o = values.url) !== null && _o !== void 0 ? _o : "http://127.0.0.1:3000",
-                        message: (_c = values.message) === null || _c === void 0 ? void 0 : _c[0],
-                        bearerToken: values["bearer-token"],
-                        text: values.text,
-                    });
-                }
-                yield runChat(Object.assign(Object.assign(Object.assign({ baseUrl: (_p = values.url) !== null && _p !== void 0 ? _p : "http://127.0.0.1:3000" }, (((_d = values.message) === null || _d === void 0 ? void 0 : _d[0]) === undefined
-                    ? {}
-                    : { message: values.message[0] })), (values["bearer-token"] === undefined
-                    ? {}
-                    : { bearerToken: values["bearer-token"] })), (values["no-color"] ? { noColor: true } : {})));
-                return 0;
+                return cmdChat(axFromOptions({
+                    dir,
+                    messages: values.message,
+                    url: values.url,
+                    prod: values.prod,
+                    team: values.team,
+                    apiKey: values["api-key"],
+                    slug: values.slug,
+                    sessionId: (_l = values["session-id"]) !== null && _l !== void 0 ? _l : values.session,
+                    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.
+                    sessionId: (_o = (_m = positionals[0]) !== null && _m !== void 0 ? _m : values["session-id"]) !== null && _o !== void 0 ? _o : 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": {
+                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"],
+                }));
+            }
+            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: (_p = values["session-id"]) !== null && _p !== void 0 ? _p : values.session,
+                    print: values.print,
+                }));
             }
             case "validate": {
                 const mounts = yield loadMounts(dir);
@@ -478,7 +645,7 @@ function main(argv) {
             case "info": {
                 const mounts = yield loadMounts(dir);
                 if (values.json) {
-                    const payload = mounts.length === 1 && ((_e = mounts[0]) === null || _e === void 0 ? void 0 : _e.slug) === ""
+                    const payload = mounts.length === 1 && ((_c = mounts[0]) === null || _c === void 0 ? void 0 : _c.slug) === ""
                         ? projectInfo(mounts[0].project)
                         : {
                             agents: mounts.map(({ slug, project }) => (Object.assign({ slug }, projectInfo(project)))),
@@ -486,7 +653,7 @@ function main(argv) {
                     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
                     return 0;
                 }
-                if (mounts.length > 1 || ((_f = mounts[0]) === null || _f === void 0 ? void 0 : _f.slug) !== "") {
+                if (mounts.length > 1 || ((_d = mounts[0]) === null || _d === void 0 ? void 0 : _d.slug) !== "") {
                     process.stdout.write(`${mounts.length} agents under ${dir}:\n\n`);
                     for (const { slug, project } of mounts) {
                         const info = projectInfo(project);
@@ -495,7 +662,7 @@ function main(argv) {
                     const anyError = mounts.some((m) => m.project.diagnostics.some((d) => d.severity === "error"));
                     return anyError ? 1 : 0;
                 }
-                const project = (_g = mounts[0]) === null || _g === void 0 ? void 0 : _g.project;
+                const project = (_e = mounts[0]) === null || _e === void 0 ? void 0 : _e.project;
                 const info = projectInfo(project);
                 const lines = [];
                 lines.push(`agent: ${info.name}`);
@@ -512,15 +679,27 @@ function main(argv) {
                     "(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", (_q = (_h = info.hosting) === null || _h === void 0 ? void 0 : _h.egressDomains) !== null && _q !== void 0 ? _q : []));
-                lines.push(section("hosting secret names", (_r = (_j = info.hosting) === null || _j === void 0 ? void 0 : _j.secretNames) !== null && _r !== void 0 ? _r : []));
+                lines.push(section("hosting egress domains", (_q = (_f = info.hosting) === null || _f === void 0 ? void 0 : _f.egressDomains) !== null && _q !== void 0 ? _q : []));
+                lines.push(section("hosting secret names", (_r = (_g = info.hosting) === null || _g === void 0 ? void 0 : _g.secretNames) !== null && _r !== void 0 ? _r : []));
                 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 ? 3000 : Number.parseInt(values.port, 10);
                 if (Number.isNaN(port) || port < 0 || port > 65535) {
                     process.stderr.write(`invalid --port: ${values.port}\n`);
@@ -536,29 +715,42 @@ function main(argv) {
                     process.stderr.write(`invalid --mode: ${mode} (expected "single" or "multi")\n`);
                     return 1;
                 }
-                const serveOptions = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ port }, (values.host === undefined ? {} : { host: values.host })), (mode === undefined ? {} : { mode: mode })), { dev: values.dev }), (values["api-key"] === undefined
-                    ? {}
-                    : { apiKey: values["api-key"] })), (values["state-root"] === undefined
-                    ? {}
-                    : { stateRoot: values["state-root"] })), (values["bearer-token"] === undefined
-                    ? {}
-                    : { authToken: values["bearer-token"] })), (values["allow-anonymous"] ? { allowAnonymous: true } : {})), (values["no-schedules"] ? { schedules: false } : {})), (values["no-playground"] ? { playground: false } : {})), (values["no-docs"] ? { docs: false } : {})), (values["public-url"] === undefined
-                    ? {}
-                    : { publicUrl: values["public-url"] })), (values["cursor-events"]
-                    ? { cursorEvents: { repos: (_s = values.repo) !== null && _s !== void 0 ? _s : [] } }
-                    : {}));
+                const dev = command === "dev" || values.dev === true;
+                const style = stdoutPalette();
+                const serveOptions = {
+                    port,
+                    host: values.host,
+                    mode: mode,
+                    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,
+                    schedules: values["no-schedules"] === true ? false : undefined,
+                    playground: values["no-playground"] === true ? false : undefined,
+                    docs: values["no-docs"] === true ? false : undefined,
+                    publicUrl: values["public-url"],
+                    cursorEvents: values["cursor-events"] === true
+                        ? { repos: (_s = values.repo) !== null && _s !== void 0 ? _s : [] }
+                        : undefined,
+                    // Soft boot logs (GitHub auth, etc.) stay secondary to the banner.
+                    logger: (line) => {
+                        process.stdout.write(`${style.dim(line)}\n`);
+                    },
+                };
                 const enterToRestart = process.stdin.isTTY === true;
                 const bannerOpts = {
                     noPlayground: values["no-playground"] === true,
-                    dev: values.dev === true,
+                    dev,
                     bearerToken: values["bearer-token"] !== undefined,
                     noSchedules: values["no-schedules"] === true,
                 };
                 const start = () => __awaiter(this, void 0, void 0, function* () {
-                    const next = yield serve(dir, serveOptions);
+                    const next = yield serve(serveDir, serveOptions);
                     printServeBanner(next, bannerOpts);
                     if (enterToRestart) {
-                        process.stdout.write("  press Enter to restart\n");
+                        process.stdout.write(style.dim("  press Enter to restart\n"));
                     }
                     return next;
                 });
@@ -586,10 +778,16 @@ function main(argv) {
                             return;
                         }
                         restarting = true;
-                        process.stdout.write("\nrestarting…\n");
-                        void handle
-                            .close()
-                            .then(start)
+                        // Close + re-serve reloads authored agent modules and respawns Vite.
+                        // Hold the "restarting…" frame briefly so a fast close doesn't look
+                        // like Enter did nothing.
+                        clearTerminal();
+                        process.stdout.write(style.dim("restarting…\n"));
+                        void Promise.all([handle.close(), sleep(450)])
+                            .then(() => {
+                            clearTerminal();
+                            return start();
+                        })
                             .then((next) => {
                             handle = next;
                         })
@@ -619,21 +817,37 @@ function deployOptionsFromValues(values) {
     return Object.assign(Object.assign(Object.assign({}, (values.team === undefined ? {} : { team: values.team })), { json: values.json === true, noWait: values["no-wait"] === true }), (values["api-key"] === undefined ? {} : { apiKey: values["api-key"] }));
 }
 function axFromOptions(partial) {
-    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ dir: partial.dir }, (partial.cwd === undefined ? {} : { cwd: partial.cwd })), (partial.slug === undefined ? {} : { slug: partial.slug })), (partial.bearerToken === undefined
-        ? {}
-        : { bearerToken: partial.bearerToken })), (partial.stateRoot === undefined
-        ? {}
-        : { stateRoot: partial.stateRoot })), (partial.messages === undefined ? {} : { messages: partial.messages })), (partial.sessionId === undefined
-        ? {}
-        : { sessionId: partial.sessionId })), (partial.continuationToken === undefined
-        ? {}
-        : { continuationToken: partial.continuationToken })), (partial.timeoutMs === undefined
-        ? {}
-        : { timeoutMs: partial.timeoutMs })), (partial.events === undefined ? {} : { events: partial.events })), (partial.text === undefined ? {} : { text: partial.text })), (partial.json === undefined ? {} : { json: partial.json })), (partial.list === undefined ? {} : { list: partial.list })), (partial.verbose === undefined ? {} : { verbose: partial.verbose })), (partial.tags === undefined ? {} : { tags: partial.tags })), (partial.evalIds === undefined ? {} : { evalIds: partial.evalIds })), (partial.initTarget === undefined
-        ? {}
-        : { initTarget: partial.initTarget })), (partial.toolName === undefined ? {} : { toolName: partial.toolName })), (partial.toolInput === undefined
-        ? {}
-        : { toolInput: partial.toolInput })), (partial.url === undefined ? {} : { url: partial.url })), (partial.stream === undefined ? {} : { stream: partial.stream }));
+    return {
+        dir: partial.dir,
+        cwd: partial.cwd,
+        slug: partial.slug,
+        bearerToken: partial.bearerToken,
+        stateRoot: partial.stateRoot,
+        messages: partial.messages,
+        sessionId: partial.sessionId,
+        continuationToken: partial.continuationToken,
+        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,
+        toolName: partial.toolName,
+        toolInput: partial.toolInput,
+        url: partial.url,
+        prod: partial.prod,
+        team: partial.team,
+        apiKey: partial.apiKey,
+        fetchImpl: partial.fetchImpl,
+        stream: partial.stream,
+        noColor: partial.noColor,
+        once: partial.once,
+        rawEvents: partial.rawEvents,
+        print: partial.print,
+    };
 }
 function loadMessages(messages, messagesFile) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -667,30 +881,6 @@ function parseTimeoutMs(value) {
     }
     return n;
 }
-function chatJson(args) {
-    return __awaiter(this, void 0, void 0, function* () {
-        var _a;
-        if (args.message === undefined) {
-            process.stderr.write("chat --json requires --message\n");
-            return 2;
-        }
-        const result = yield runSession(Object.assign({ baseUrl: args.baseUrl, messages: [args.message] }, (args.bearerToken === undefined
-            ? {}
-            : { bearerToken: args.bearerToken })));
-        if (args.text) {
-            process.stdout.write(formatTrajectoryText(result.trajectory));
-        }
-        else {
-            console.log(JSON.stringify({
-                ok: result.ok,
-                sessionId: result.sessionId,
-                continuationToken: (_a = result.continuationToken) !== null && _a !== void 0 ? _a : null,
-                trajectory: result.trajectory,
-            }, null, 2));
-        }
-        return result.ok ? 0 : 1;
-    });
-}
 /**
  * Load mounts the same way `serve` does (multi-agent layout by default).
  */
@@ -708,62 +898,109 @@ function section(title, items) {
 function isEnterOnly(text) {
     return text.length > 0 && [...text].every((ch) => ch === "\n" || ch === "\r");
 }
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * `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) {
+    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, opts) {
-    var _a;
-    const multi = handle.agents.length > 1 || ((_a = handle.agents[0]) === null || _a === void 0 ? void 0 : _a.slug) !== "";
-    if (multi) {
-        process.stdout.write(`${handle.agents.length} agents listening on ${handle.url}\n`);
-        if (!opts.noPlayground) {
-            process.stdout.write(`  index: ${handle.url}/\n`);
-        }
-        for (const agent of handle.agents) {
-            const info = projectInfo(agent.project);
-            const suffix = opts.noPlayground
-                ? `${agent.url}/v1/session`
-                : `${agent.url}/playground`;
-            process.stdout.write(`  /${agent.slug}  ${info.name} — ${suffix}\n`);
-        }
+    var _a, _b;
+    var _c;
+    const c = stdoutPalette();
+    const agents = handle.agents;
+    if (agents.length > 1) {
+        process.stdout.write(`${agents.length} agents listening\n`);
     }
     else {
-        const info = projectInfo(handle.project);
-        process.stdout.write(`${info.name} listening on ${handle.url}\n`);
-        if (!opts.noPlayground) {
-            process.stdout.write(`  playground: ${handle.url}/playground\n`);
-        }
-        process.stdout.write(`  POST ${handle.url}/v1/session\n`);
-        process.stdout.write(`  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(`  ${route.method} ${handle.url}${route.url}\n`);
+        const info = projectInfo((_c = (_a = agents[0]) === null || _a === void 0 ? void 0 : _a.project) !== null && _c !== void 0 ? _c : handle.project);
+        process.stdout.write(`${info.name} listening\n`);
+    }
+    const playgroundUrl = resolvePlaygroundBannerUrl(handle, opts.noPlayground);
+    if (playgroundUrl !== undefined) {
+        process.stdout.write(`  playground  ${c.cyan(playgroundUrl)}\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 || ((_b = agents[0]) === null || _b === void 0 ? void 0 : _b.slug) !== "") {
+            for (const agent of agents) {
+                const info = projectInfo(agent.project);
+                process.stdout.write(c.dim(`  /${agent.slug}  ${info.name}\n`));
             }
         }
-        if (info.schedules.length > 0) {
-            const scheduleMode = opts.dev
-                ? "dev mode: dispatch with POST /v1/dev/schedules/:scheduleId"
-                : opts.noSchedules
+        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(`  schedules: ${info.schedules.map((s) => s.name).join(", ")} — ${scheduleMode}\n`);
+                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 (handle.playgroundDevUrl !== undefined) {
-        process.stdout.write(`  playground (HMR): ${handle.playgroundDevUrl}\n`);
-    }
-    if (handle.docsUrl !== undefined) {
-        process.stdout.write(`  docs: ${handle.docsUrl}\n`);
     }
     if (opts.bearerToken) {
-        process.stdout.write("  auth: bearer token required on API routes (playground has a token field)\n");
+        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(`  github: dev accepts unsigned loopback deliveries (${CLI} github forward works without a secret; set GITHUB_WEBHOOK_SECRET to verify signatures)\n`);
+        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`));
+    }
+}
+/** Prefer the Vite playground URL in --dev; otherwise the static SPA path. */
+function resolvePlaygroundBannerUrl(handle, noPlayground) {
+    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) {
     if (model === undefined) {