@cursor/july 0.1.2 → 0.1.3

package/src/bin/agent-serve.ts

@@ -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>
@@ -22,13 +24,18 @@ import {
   serve,
 } from "../index.js";
 import { registerAuthoredModuleLoaders } from "../internal/authored-loaders.js";
-import { runChat } from "../internal/chat-client.js";
 import {
   type AxCliOptions,
   cmdCall,
+  cmdChat,
   cmdEval,
   cmdInit,
+  cmdLogs,
+  cmdPlayground,
+  cmdResume,
   cmdRun,
+  cmdSession,
+  cmdSessions,
   cmdTrajectory,
 } from "../internal/cli-ax.js";
 import {
@@ -44,8 +51,7 @@ import {
   type DeployCliOptions,
 } 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";
 import type { AgentProject, AgentServeHandle } from "../types.js";
 
 const HELP = `${CLI} — serve a filesystem-defined Cursor agent over channels
@@ -55,24 +61,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>]...
@@ -89,15 +113,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
@@ -110,8 +160,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.
@@ -132,6 +185,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).
@@ -152,28 +206,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.
@@ -181,7 +256,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
@@ -191,10 +268,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
@@ -215,7 +297,7 @@ Options:
 `;
 
 async function main(argv: string[]): Promise<number> {
-  const [command, ...rest] = argv;
+  const [command, ...restIn] = argv;
   if (
     command === undefined ||
     command === "help" ||
@@ -226,6 +308,13 @@ async function main(argv: string[]): Promise<number> {
     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,
@@ -240,10 +329,12 @@ async function main(argv: string[]): Promise<number> {
       "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" },
@@ -260,6 +351,8 @@ async function main(argv: string[]): Promise<number> {
       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" },
@@ -287,6 +380,7 @@ async function main(argv: string[]): Promise<number> {
       "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 },
     },
@@ -352,6 +446,7 @@ async function main(argv: string[]): Promise<number> {
       return cmdInit({
         dir,
         initTarget: positionals[0],
+        json: values.json,
       });
     }
 
@@ -381,6 +476,7 @@ async function main(argv: string[]): Promise<number> {
         ...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 }),
@@ -454,6 +550,9 @@ async function main(argv: string[]): Promise<number> {
               : 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"],
@@ -471,6 +570,9 @@ async function main(argv: string[]): Promise<number> {
           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"],
@@ -502,6 +604,9 @@ async function main(argv: string[]): Promise<number> {
           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"],
@@ -512,25 +617,110 @@ async function main(argv: string[]): Promise<number> {
     }
 
     case "chat": {
-      if (values.json) {
-        return chatJson({
-          baseUrl: values.url ?? "http://127.0.0.1:3000",
-          message: (values.message as string[] | undefined)?.[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: values["session-id"] ?? values.session,
+          continuationToken: values["continuation-token"],
           bearerToken: values["bearer-token"],
+          json: values.json,
           text: values.text,
-        });
-      }
-      await runChat({
-        baseUrl: values.url ?? "http://127.0.0.1:3000",
-        ...((values.message as string[] | undefined)?.[0] === undefined
-          ? {}
-          : { message: (values.message as string[])[0]! }),
-        ...(values["bearer-token"] === undefined
-          ? {}
-          : { bearerToken: values["bearer-token"] }),
-        ...(values["no-color"] ? { noColor: true } : {}),
-      });
-      return 0;
+          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: 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": {
+      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: values["session-id"] ?? values.session,
+          print: values.print,
+        })
+      );
     }
 
     case "validate": {
@@ -645,7 +835,19 @@ async function main(argv: string[]): Promise<number> {
       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) {
@@ -668,44 +870,45 @@ async function main(argv: string[]): Promise<number> {
         );
         return 1;
       }
+      const dev = command === "dev" || values.dev === true;
+      const style = stdoutPalette();
       const serveOptions = {
         port,
-        ...(values.host === undefined ? {} : { host: values.host }),
-        ...(mode === undefined ? {} : { mode: mode as "single" | "multi" }),
-        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: values.repo ?? [] } }
-          : {}),
+        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,
+        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: values.repo ?? [] }
+            : undefined,
+        // Soft boot logs (GitHub auth, etc.) stay secondary to the banner.
+        logger: (line: string) => {
+          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 = async (): Promise<AgentServeHandle> => {
-        const next = await serve(dir, serveOptions);
+        const next = await 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;
       };
@@ -738,10 +941,16 @@ async function main(argv: string[]): Promise<number> {
             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;
             })
@@ -790,40 +999,34 @@ function axFromOptions(
 ): AxCliOptions {
   return {
     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 }),
+    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,
   };
 }
 
@@ -862,42 +1065,6 @@ function parseTimeoutMs(value: string | undefined): number | undefined {
   return n;
 }
 
-async function chatJson(args: {
-  baseUrl: string;
-  message?: string;
-  bearerToken?: string;
-  text?: boolean;
-}): Promise<number> {
-  if (args.message === undefined) {
-    process.stderr.write("chat --json requires --message\n");
-    return 2;
-  }
-  const result = await runSession({
-    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: result.continuationToken ?? null,
-          trajectory: result.trajectory,
-        },
-        null,
-        2
-      )
-    );
-  }
-  return result.ok ? 0 : 1;
-}
-
 /**
  * Load mounts the same way `serve` does (multi-agent layout by default).
  */
@@ -918,6 +1085,42 @@ function isEnterOnly(text: string): boolean {
   return text.length > 0 && [...text].every((ch) => ch === "\n" || ch === "\r");
 }
 
+function sleep(ms: number): Promise<void> {
+  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: {
+  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: {
@@ -927,57 +1130,66 @@ function printServeBanner(
     noSchedules: boolean;
   }
 ): void {
-  const multi = handle.agents.length > 1 || handle.agents[0]?.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`);
-    }
+  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;
+    const info = projectInfo(agents[0]?.project ?? 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 || agents[0]?.slug !== "") {
+      for (const agent of agents) {
+        const info = projectInfo(agent.project);
+        process.stdout.write(c.dim(`  /${agent.slug}  ${info.name}\n`));
       }
-      for (const route of channel.routes) {
-        process.stdout.write(`  ${route.method} ${handle.url}${route.url}\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.dev
-        ? "dev mode: dispatch with POST /v1/dev/schedules/:scheduleId"
-        : opts.noSchedules
+      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"
+      c.dim(
+        "  auth: bearer token required on API routes (playground has a token field)\n"
+      )
     );
   }
   if (
@@ -989,11 +1201,33 @@ function printServeBanner(
     )
   ) {
     process.stdout.write(
-      `  github: dev accepts unsigned loopback deliveries (${CLI} github forward works without a secret; set GITHUB_WEBHOOK_SECRET to verify signatures)\n`
+      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: 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)";