@cursor/july 0.1.2 → 0.1.4

package/src/internal/cli-ax.ts

@@ -12,6 +12,10 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { serve } from "../index.js";
 import type { AgentServeHandle } from "../types.js";
+import { lookupSessionContinuation, runChat } from "./chat-client.js";
+import { cmdLogin } from "./cli-cursor.js";
+import { resolveDeployAuth } from "./cli-deploy.js";
+import { resolveApiKey } from "./cursor/credentials.js";
 import { CLI_COMMAND_NAME } from "./distribution.js";
 import {
   discoverEvals,
@@ -19,10 +23,29 @@ import {
   filterDiscoveredEvals,
   runDiscoveredEvals,
 } from "./eval-runner.js";
-import { initProject, printInitGuide } from "./init-project.js";
+import {
+  formatInitNextSteps,
+  formatInitScaffoldSummary,
+  initNextCommands,
+  initProject,
+  installScaffoldDependencies,
+  printInitGuide,
+} from "./init-project.js";
+import { offerInstallCursorSkills } from "./install-cursor-skills.js";
+import { runLogsTail, sanitizeCustomerError } from "./logs-client.js";
+import { openBrowser } from "./open-browser.js";
+import { startPlaygroundProxy } from "./playground-proxy.js";
+import { resolveProdSlug, resolveProdTarget } from "./resolve-prod-target.js";
 import { runSession } from "./run-client.js";
+import {
+  fetchSessionEvents,
+  formatSessionsTable,
+  listSessions,
+  resolvePreviousSessionId,
+} from "./sessions-client.js";
 import { createStreamProgress } from "./stream-progress.js";
 import {
+  buildTrajectory,
   formatTrajectoryText,
   loadTrajectoryFromEventsFile,
 } from "./trajectory.js";
@@ -30,7 +53,11 @@ import {
 export interface AxCliOptions {
   cwd?: string;
   dir: string;
-  /** Agent slug when multiple agents are mounted. */
+  /**
+   * Local multi-agent mount slug, or (with `--prod`) the hosted deployment
+   * slug. When `--prod` is set and this is omitted, the slug is derived from
+   * the directory name (same as `deploy`).
+   */
   slug?: string;
   bearerToken?: string;
   stateRoot?: string;
@@ -59,13 +86,52 @@ export interface AxCliOptions {
   toolName?: string;
   /** JSON input for `call`. */
   toolInput?: string;
-  /** Remote agent base URL (skip local host) for run/eval. */
+  /** Remote agent base URL (skip local host) for run/eval/chat. */
   url?: string;
+  /**
+   * Route chat/resume/run/call/eval/logs/sessions at the team's hosted
+   * deployment
+   * instead of a local ephemeral server. Mutually exclusive with `--url`.
+   */
+  prod?: boolean;
+  /** Cursor team id for `--prod` (defaults to the account's team). */
+  team?: string;
+  /** Cursor API key override for `--prod` management calls. */
+  apiKey?: string;
+  /** Injected fetch for `--prod` tests. */
+  fetchImpl?: typeof fetch;
   /**
    * Stream live turn progress to stderr (default: stderr is a TTY).
    * Final JSON/text still goes to stdout.
    */
   stream?: boolean;
+  /** Force plain chat output even on a TTY. */
+  noColor?: boolean;
+  /** `logs`: dump current buffer / progress once and exit. */
+  once?: boolean;
+  /**
+   * `session`: print raw `{ sessionId, events }` JSON instead of a trajectory.
+   * (CLI flag `--events`; rewritten from colliding with run's `--events <file>`.)
+   */
+  rawEvents?: boolean;
+  /**
+   * `playground`: print the URL only; do not open a browser.
+   * (CLI flag `--print`.)
+   */
+  print?: boolean;
+  /**
+   * `chat --resume` / `resume` with no session id: reattach the most
+   * recently updated followable session from `/v1/sessions`.
+   */
+  resume?: boolean;
+  /** Abort signal (tests / programmatic stop of `playground` proxy). */
+  signal?: AbortSignal;
+}
+
+export interface ResolvedAgentTarget {
+  agentUrl: string;
+  headers?: Record<string, string>;
+  close?: () => Promise<void>;
 }
 
 function shouldStreamProgress(options: AxCliOptions): boolean {
@@ -136,12 +202,26 @@ async function startEphemeral(
   };
 }
 
-async function resolveTarget(
+export async function resolveTarget(
   options: AxCliOptions
-): Promise<{ agentUrl: string; close?: () => Promise<void> }> {
+): Promise<ResolvedAgentTarget> {
+  if (options.prod === true && options.url !== undefined) {
+    die("--prod and --url are mutually exclusive");
+  }
   if (options.url !== undefined) {
     return { agentUrl: options.url.replace(/\/$/, "") };
   }
+  if (options.prod === true) {
+    const prod = await resolveProdTarget({
+      dir: options.dir,
+      cwd: options.cwd,
+      slug: options.slug,
+      team: options.team,
+      apiKey: options.apiKey,
+      fetchImpl: options.fetchImpl,
+    });
+    return { agentUrl: prod.agentUrl, headers: prod.headers };
+  }
   return startEphemeral(options);
 }
 
@@ -151,27 +231,236 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
     printInitGuide();
     return 0;
   }
-  const dir = resolve(options.cwd ?? process.cwd(), target);
+  const cwd = options.cwd ?? process.cwd();
+  const dir = resolve(cwd, target);
   const result = await initProject({ dir });
+  let signedIn = (await resolveApiKey()) !== undefined;
+
+  // Machine-readable path: install deps (piped), never block on browser login.
+  if (options.json) {
+    const install = await installScaffoldDependencies(result.rootDir, {
+      stdio: "pipe",
+    });
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: install.ok,
+          directory: result.rootDir,
+          created: result.created,
+          skipped: result.skipped,
+          installed: install.ok,
+          installError: install.ok
+            ? null
+            : install.stderr.trim() || `npm install exited ${install.exitCode}`,
+          next: initNextCommands({
+            rootDir: result.rootDir,
+            cwd,
+            signedIn,
+          }),
+        },
+        null,
+        2
+      )}\n`
+    );
+    return install.ok ? 0 : 1;
+  }
+
   process.stdout.write(
-    `${JSON.stringify(
-      {
-        ok: true,
-        directory: result.rootDir,
-        created: result.files,
-        next: [
-          `cd ${dir === process.cwd() ? "." : dir}`,
-          `${CLI_COMMAND_NAME} validate`,
-          `${CLI_COMMAND_NAME} info --json`,
-          `${CLI_COMMAND_NAME} run --message "hello"`,
-          `${CLI_COMMAND_NAME} eval`,
-        ],
-      },
-      null,
-      2
-    )}\n`
+    formatInitScaffoldSummary({
+      rootDir: result.rootDir,
+      files: result.files,
+    })
   );
-  return 0;
+  process.stdout.write("Installing npm packages\n\n");
+  const install = await installScaffoldDependencies(result.rootDir, {
+    stdio: "inherit",
+  });
+  if (!install.ok) {
+    process.stderr.write(
+      `\nnpm install failed (exit ${install.exitCode}). Fix the install, then run ${CLI_COMMAND_NAME} dev.\n`
+    );
+    return install.exitCode || 1;
+  }
+  process.stdout.write("\n");
+
+  // Personal Cursor skills so coding agents can pick up create-agent / debug / …
+  try {
+    await offerInstallCursorSkills();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(
+      `\nCould not install Cursor skills (${message}). Continuing init.\n\n`
+    );
+  }
+
+  let loginExit = 0;
+  if (!signedIn) {
+    process.stdout.write("Signing you in to Cursor\n\n");
+    loginExit = await cmdLogin({});
+    signedIn = loginExit === 0 && (await resolveApiKey()) !== undefined;
+    process.stdout.write("\n");
+  }
+
+  process.stdout.write(
+    formatInitNextSteps({
+      rootDir: result.rootDir,
+      cwd,
+      signedIn,
+    })
+  );
+  return loginExit;
+}
+
+/**
+ * `chat` — talk to a running (or `--prod` hosted) agent. With `--json`,
+ * prints a trajectory instead of the interactive UI.
+ */
+/**
+ * `resume [sessionId]` — reattach the interactive chat REPL to an existing
+ * session. When the id is omitted, picks the most recently updated
+ * followable session from `/v1/sessions` (same as `chat --resume`).
+ * Looks up the continuation token via `/v1/sessions` when
+ * `--continuation-token` is omitted. Same flags as `chat` (`--prod`,
+ * `--message`, `--json`, …). `--session` is accepted as a redundant
+ * alias for the positional id.
+ */
+export async function cmdResume(
+  sessionId: string | undefined,
+  options: AxCliOptions
+): Promise<number> {
+  const resolved = trimNonEmpty(sessionId) ?? trimNonEmpty(options.sessionId);
+  if (resolved !== undefined) {
+    return cmdChat({
+      ...options,
+      sessionId: resolved,
+      resume: false,
+    });
+  }
+  return cmdChat({
+    ...options,
+    sessionId: undefined,
+    resume: true,
+  });
+}
+
+function trimNonEmpty(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+export async function cmdChat(options: AxCliOptions): Promise<number> {
+  const message = options.messages?.[0];
+  // chat never starts an ephemeral server — default to local serve URL.
+  const target = await resolveTarget({
+    ...options,
+    url:
+      options.prod === true
+        ? undefined
+        : (options.url ?? "http://127.0.0.1:3000"),
+  });
+
+  let sessionId = trimNonEmpty(options.sessionId);
+  // `--resume` without an id → most recently updated followable session.
+  // An explicit `--session` / positional id always wins.
+  if (options.resume === true && sessionId === undefined) {
+    try {
+      const previous = await resolvePreviousSessionId({
+        baseUrl: target.agentUrl,
+        auth: {
+          bearerToken: options.bearerToken,
+          headers: target.headers,
+        },
+        fetchImpl: options.fetchImpl,
+      });
+      if (previous === undefined) {
+        process.stderr.write(
+          "No previous followable session found. Start one with " +
+            `\`${CLI_COMMAND_NAME} chat\` or pass a session id.\n`
+        );
+        return 1;
+      }
+      sessionId = previous;
+    } catch (error) {
+      process.stderr.write(
+        `${error instanceof Error ? error.message : String(error)}\n`
+      );
+      return 1;
+    }
+  }
+
+  if (options.json) {
+    if (message === undefined) {
+      process.stderr.write("chat --json requires --message\n");
+      return 2;
+    }
+    let continuationToken = options.continuationToken;
+    if (
+      sessionId !== undefined &&
+      (continuationToken === undefined || continuationToken === "")
+    ) {
+      try {
+        continuationToken = await lookupSessionContinuation({
+          baseUrl: target.agentUrl,
+          sessionId,
+          auth: {
+            bearerToken: options.bearerToken,
+            headers: target.headers,
+          },
+        });
+      } catch (error) {
+        process.stderr.write(
+          `${error instanceof Error ? error.message : String(error)}\n`
+        );
+        return 1;
+      }
+    }
+    const result = await runSession({
+      baseUrl: target.agentUrl,
+      messages: [message],
+      sessionId,
+      continuationToken,
+      bearerToken: options.bearerToken,
+      headers: target.headers,
+    });
+    if (options.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;
+  }
+
+  try {
+    await runChat({
+      baseUrl: target.agentUrl,
+      message,
+      sessionId,
+      continuationToken: options.continuationToken,
+      bearerToken: options.bearerToken,
+      headers: target.headers,
+      noColor: options.noColor,
+    });
+    return 0;
+  } catch (error) {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`
+    );
+    return 1;
+  }
 }
 
 export async function cmdRun(options: AxCliOptions): Promise<number> {
@@ -191,21 +480,12 @@ export async function cmdRun(options: AxCliOptions): Promise<number> {
     const result = await runSession({
       baseUrl: target.agentUrl,
       messages,
-      ...(options.sessionId === undefined
-        ? {}
-        : { sessionId: options.sessionId }),
-      ...(options.continuationToken === undefined
-        ? {}
-        : { continuationToken: options.continuationToken }),
-      ...(options.bearerToken === undefined
-        ? {}
-        : { bearerToken: options.bearerToken }),
-      ...(options.timeoutMs === undefined
-        ? {}
-        : { timeoutMs: options.timeoutMs }),
-      ...(progress === undefined
-        ? {}
-        : { onEvent: (e) => progress.onEvent(e) }),
+      sessionId: options.sessionId,
+      continuationToken: options.continuationToken,
+      bearerToken: options.bearerToken,
+      headers: target.headers,
+      timeoutMs: options.timeoutMs,
+      onEvent: progress === undefined ? undefined : (e) => progress.onEvent(e),
     });
 
     let eventsPath: string | undefined;
@@ -227,8 +507,26 @@ export async function cmdRun(options: AxCliOptions): Promise<number> {
     }
 
     const playgroundUrl =
-      options.url !== undefined
-        ? `${target.agentUrl.replace(/\/$/, "")}/playground?sessionId=${encodeURIComponent(result.sessionId)}`
+      options.prod === true
+        ? null
+        : options.url !== undefined
+          ? `${target.agentUrl.replace(/\/$/, "")}/playground?sessionId=${encodeURIComponent(result.sessionId)}`
+          : null;
+    const playgroundHint =
+      options.prod === true
+        ? [
+            CLI_COMMAND_NAME,
+            "playground",
+            "--prod",
+            ...(options.slug !== undefined && options.slug.trim() !== ""
+              ? ["--slug", options.slug.trim()]
+              : []),
+            ...(options.team !== undefined && options.team.trim() !== ""
+              ? ["--team", options.team.trim()]
+              : []),
+            "--session",
+            result.sessionId,
+          ].join(" ")
         : null;
 
     if (options.text) {
@@ -238,6 +536,8 @@ export async function cmdRun(options: AxCliOptions): Promise<number> {
       }
       if (playgroundUrl !== null) {
         process.stderr.write(`playground: ${playgroundUrl}\n`);
+      } else if (playgroundHint !== null) {
+        process.stderr.write(`playground: ${playgroundHint}\n`);
       }
     } else {
       console.log(
@@ -248,12 +548,15 @@ export async function cmdRun(options: AxCliOptions): Promise<number> {
             continuationToken: result.continuationToken ?? null,
             trace: eventsPath ?? null,
             playgroundUrl,
+            playgroundHint,
             visualize:
-              playgroundUrl !== null
-                ? `Open ${playgroundUrl}`
-                : eventsPath !== undefined
-                  ? `Start the playground (${CLI_COMMAND_NAME} serve --dir ${options.dir}), then Open trace → ${eventsPath}`
-                  : null,
+              playgroundHint !== null
+                ? `Run ${playgroundHint}`
+                : playgroundUrl !== null
+                  ? `Open ${playgroundUrl}`
+                  : eventsPath !== undefined
+                    ? `Start the playground (${CLI_COMMAND_NAME} serve --dir ${options.dir}), then Open trace → ${eventsPath}`
+                    : null,
             trajectory: result.trajectory,
           },
           null,
@@ -296,22 +599,25 @@ export async function cmdCall(options: AxCliOptions): Promise<number> {
 
   const target = await resolveTarget(options);
   try {
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+    };
+    if (target.headers !== undefined) {
+      Object.assign(headers, target.headers);
+    }
+    if (options.bearerToken !== undefined) {
+      headers.authorization = `Bearer ${options.bearerToken}`;
+    }
+    const body: { input: unknown; sessionId?: string } = { input };
+    if (options.sessionId !== undefined) {
+      body.sessionId = options.sessionId;
+    }
     const response = await fetch(
       `${target.agentUrl}/v1/tools/${encodeURIComponent(toolName)}`,
       {
         method: "POST",
-        headers: {
-          "content-type": "application/json",
-          ...(options.bearerToken === undefined
-            ? {}
-            : { authorization: `Bearer ${options.bearerToken}` }),
-        },
-        body: JSON.stringify({
-          input,
-          ...(options.sessionId === undefined
-            ? {}
-            : { sessionId: options.sessionId }),
-        }),
+        headers,
+        body: JSON.stringify(body),
       }
     );
     const payload: unknown = await response
@@ -399,22 +705,19 @@ export async function cmdEval(options: AxCliOptions): Promise<number> {
     const results = await runDiscoveredEvals({
       projectRoot,
       baseUrl: target.agentUrl,
-      ...(options.evalIds === undefined || options.evalIds.length === 0
-        ? {}
-        : { filterIds: options.evalIds }),
-      ...(options.tags === undefined || options.tags.length === 0
-        ? {}
-        : { tags: options.tags }),
-      ...(options.timeoutMs === undefined
-        ? {}
-        : { timeoutMs: options.timeoutMs }),
-      ...(options.bearerToken === undefined
-        ? {}
-        : { bearerToken: options.bearerToken }),
+      filterIds:
+        options.evalIds === undefined || options.evalIds.length === 0
+          ? undefined
+          : options.evalIds,
+      tags:
+        options.tags === undefined || options.tags.length === 0
+          ? undefined
+          : options.tags,
+      timeoutMs: options.timeoutMs,
+      bearerToken: options.bearerToken,
+      headers: target.headers,
       verbose: Boolean(options.verbose) || stream,
-      ...(progress === undefined
-        ? {}
-        : { onEvent: (e) => progress.onEvent(e) }),
+      onEvent: progress === undefined ? undefined : (e) => progress.onEvent(e),
     });
 
     if (results.length === 0) {
@@ -472,3 +775,389 @@ function printEvalResults(
   }
   return failed === 0 ? 0 : 1;
 }
+
+/**
+ * `logs` — follow deploy progress (`--prod`) then runtime agent logs.
+ * Local / `--url` tails `/v1/logs` only.
+ */
+export async function cmdLogs(options: AxCliOptions): Promise<number> {
+  if (options.prod === true && options.url !== undefined) {
+    process.stderr.write("--prod and --url are mutually exclusive\n");
+    return 2;
+  }
+
+  const controller = new AbortController();
+  const onSignal = (): void => {
+    controller.abort();
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+
+  try {
+    if (options.prod === true) {
+      const slug = resolveProdSlug({
+        dir: options.dir,
+        cwd: options.cwd,
+        slug: options.slug,
+      });
+      const auth = await resolveDeployAuth({
+        team: options.team,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+      });
+      if (typeof auth === "number") {
+        return auth;
+      }
+      await runLogsTail({
+        prod: true,
+        dir: options.dir,
+        cwd: options.cwd,
+        slug,
+        team: options.team,
+        apiKey: options.apiKey,
+        bearerToken: options.bearerToken,
+        once: options.once,
+        json: options.json,
+        fetchImpl: options.fetchImpl,
+        signal: controller.signal,
+        getDeployment: () =>
+          auth.client.getDeployment({ teamId: auth.teamId, slug }),
+        resolveRuntime: async () => {
+          const target = await resolveProdTarget({
+            dir: options.dir,
+            cwd: options.cwd,
+            slug,
+            team: options.team,
+            apiKey: options.apiKey,
+            fetchImpl: options.fetchImpl,
+            err: () => {},
+          });
+          return { agentUrl: target.agentUrl, headers: target.headers };
+        },
+      });
+      return 0;
+    }
+
+    await runLogsTail({
+      dir: options.dir,
+      cwd: options.cwd,
+      url: options.url ?? "http://127.0.0.1:3000",
+      bearerToken: options.bearerToken,
+      once: options.once,
+      json: options.json,
+      fetchImpl: options.fetchImpl,
+      signal: controller.signal,
+    });
+    return 0;
+  } catch (error) {
+    if (controller.signal.aborted) {
+      return 0;
+    }
+    const raw = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${sanitizeCustomerError(raw)}\n`);
+    return 1;
+  } finally {
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
+  }
+}
+
+/** Resolve local / `--url` / `--prod` agent base URL + request headers. */
+async function resolveSessionTarget(
+  options: AxCliOptions
+): Promise<{ agentUrl: string; headers?: Record<string, string> } | number> {
+  if (options.prod === true && options.url !== undefined) {
+    process.stderr.write("--prod and --url are mutually exclusive\n");
+    return 2;
+  }
+  if (options.prod === true) {
+    try {
+      const target = await resolveProdTarget({
+        dir: options.dir,
+        cwd: options.cwd,
+        slug: options.slug,
+        team: options.team,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+      });
+      return { agentUrl: target.agentUrl, headers: target.headers };
+    } catch (error) {
+      process.stderr.write(
+        `${sanitizeCustomerError(
+          error instanceof Error ? error.message : String(error)
+        )}\n`
+      );
+      return 1;
+    }
+  }
+  return {
+    agentUrl: (options.url ?? "http://127.0.0.1:3000").replace(/\/$/, ""),
+  };
+}
+
+/**
+ * `sessions` — list sessions on a running (or `--prod` hosted) agent.
+ */
+export async function cmdSessions(options: AxCliOptions): Promise<number> {
+  const target = await resolveSessionTarget(options);
+  if (typeof target === "number") {
+    return target;
+  }
+  try {
+    const sessions = await listSessions({
+      baseUrl: target.agentUrl,
+      auth: {
+        bearerToken: options.bearerToken,
+        headers: target.headers,
+      },
+      fetchImpl: options.fetchImpl,
+    });
+    if (options.json === true) {
+      process.stdout.write(`${JSON.stringify({ sessions }, null, 2)}\n`);
+      return 0;
+    }
+    process.stdout.write(formatSessionsTable(sessions));
+    return 0;
+  } catch (error) {
+    process.stderr.write(
+      `${sanitizeCustomerError(
+        error instanceof Error ? error.message : String(error)
+      )}\n`
+    );
+    return 1;
+  }
+}
+
+/**
+ * `session <id>` — view a full session (trajectory text by default).
+ * `--json` → trajectory JSON; `--events` (`rawEvents`) → raw event list.
+ * Interactive reattach: `resume [id]` / `chat --resume` (or `chat --session`).
+ */
+export async function cmdSession(
+  sessionId: string | undefined,
+  options: AxCliOptions
+): Promise<number> {
+  if (sessionId === undefined || sessionId.trim() === "") {
+    process.stderr.write(
+      `Usage: ${CLI_COMMAND_NAME} session <sessionId> [--url | --prod] [--json | --text | --events]\n`
+    );
+    return 2;
+  }
+  if (options.rawEvents === true && options.json === true) {
+    process.stderr.write("--events and --json are mutually exclusive\n");
+    return 2;
+  }
+
+  const target = await resolveSessionTarget(options);
+  if (typeof target === "number") {
+    return target;
+  }
+
+  try {
+    const events = await fetchSessionEvents({
+      baseUrl: target.agentUrl,
+      sessionId,
+      auth: {
+        bearerToken: options.bearerToken,
+        headers: target.headers,
+      },
+      fetchImpl: options.fetchImpl,
+    });
+
+    if (options.rawEvents === true) {
+      process.stdout.write(
+        `${JSON.stringify({ sessionId, events }, null, 2)}\n`
+      );
+      return 0;
+    }
+
+    const trajectory = buildTrajectory(events);
+    if (options.json === true) {
+      process.stdout.write(`${JSON.stringify(trajectory, null, 2)}\n`);
+      return 0;
+    }
+    process.stdout.write(formatTrajectoryText(trajectory));
+    return 0;
+  } catch (error) {
+    process.stderr.write(
+      `${sanitizeCustomerError(
+        error instanceof Error ? error.message : String(error)
+      )}\n`
+    );
+    return 1;
+  }
+}
+
+/**
+ * `playground` — open the web UI against local / `--url` / `--prod`.
+ *
+ * Hosted engines need short-lived access headers a browser cannot set, so
+ * `--prod` (and `--bearer-token`) run a loopback reverse proxy that injects
+ * them. Ctrl-C stops the proxy.
+ */
+export async function cmdPlayground(options: AxCliOptions): Promise<number> {
+  if (options.prod === true && options.url !== undefined) {
+    process.stderr.write("--prod and --url are mutually exclusive\n");
+    return 2;
+  }
+
+  const sessionId =
+    options.sessionId !== undefined && options.sessionId.trim() !== ""
+      ? options.sessionId.trim()
+      : undefined;
+
+  // Hosted: mint engineAccess and refresh it for the life of the proxy.
+  if (options.prod === true) {
+    let initial: Awaited<ReturnType<typeof resolveProdTarget>>;
+    try {
+      initial = await resolveProdTarget({
+        dir: options.dir,
+        cwd: options.cwd,
+        slug: options.slug,
+        team: options.team,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+      });
+    } catch (error) {
+      process.stderr.write(
+        `${sanitizeCustomerError(
+          error instanceof Error ? error.message : String(error)
+        )}\n`
+      );
+      return 1;
+    }
+
+    let proxy: Awaited<ReturnType<typeof startPlaygroundProxy>>;
+    try {
+      proxy = await startPlaygroundProxy({
+        upstreamUrl: initial.agentUrl,
+        headers: initial.headers,
+        expiresAt: initial.expiresAt,
+        refreshUpstream: async () => {
+          const next = await resolveProdTarget({
+            dir: options.dir,
+            cwd: options.cwd,
+            slug: options.slug ?? initial.slug,
+            team: options.team,
+            apiKey: options.apiKey,
+            fetchImpl: options.fetchImpl,
+            err: () => {},
+          });
+          return {
+            upstreamUrl: next.agentUrl,
+            headers: next.headers,
+            expiresAt: next.expiresAt,
+          };
+        },
+      });
+    } catch (error) {
+      process.stderr.write(
+        `${sanitizeCustomerError(
+          error instanceof Error ? error.message : String(error)
+        )}\n`
+      );
+      return 1;
+    }
+
+    return await runPlaygroundProxySession({
+      proxy,
+      sessionId,
+      print: options.print === true,
+      signal: options.signal,
+    });
+  }
+
+  const target = await resolveSessionTarget(options);
+  if (typeof target === "number") {
+    return target;
+  }
+
+  const needsProxy =
+    (target.headers !== undefined && Object.keys(target.headers).length > 0) ||
+    (options.bearerToken !== undefined && options.bearerToken.trim() !== "");
+
+  if (!needsProxy) {
+    const base = `${target.agentUrl.replace(/\/$/, "")}/playground`;
+    const playgroundUrl =
+      sessionId === undefined
+        ? base
+        : `${base}?sessionId=${encodeURIComponent(sessionId)}`;
+    process.stdout.write(`${playgroundUrl}\n`);
+    if (options.print !== true) {
+      openBrowser(playgroundUrl);
+    }
+    return 0;
+  }
+
+  let proxy: Awaited<ReturnType<typeof startPlaygroundProxy>>;
+  try {
+    proxy = await startPlaygroundProxy({
+      upstreamUrl: target.agentUrl,
+      headers: target.headers,
+      bearerToken: options.bearerToken,
+    });
+  } catch (error) {
+    process.stderr.write(
+      `${sanitizeCustomerError(
+        error instanceof Error ? error.message : String(error)
+      )}\n`
+    );
+    return 1;
+  }
+
+  return await runPlaygroundProxySession({
+    proxy,
+    sessionId,
+    print: options.print === true,
+    signal: options.signal,
+  });
+}
+
+async function runPlaygroundProxySession(args: {
+  proxy: Awaited<ReturnType<typeof startPlaygroundProxy>>;
+  sessionId?: string;
+  print: boolean;
+  signal?: AbortSignal;
+}): Promise<number> {
+  const { proxy } = args;
+
+  const playgroundUrl = proxy.playgroundUrl(args.sessionId);
+  process.stdout.write(`${playgroundUrl}\n`);
+  process.stderr.write(`Playground proxy on loopback (Ctrl-C to stop).\n`);
+  if (args.print !== true) {
+    openBrowser(playgroundUrl);
+  }
+
+  const controller = new AbortController();
+  const onSignal = (): void => {
+    controller.abort();
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  const external = args.signal;
+  if (external !== undefined) {
+    if (external.aborted) {
+      controller.abort();
+    } else {
+      external.addEventListener("abort", onSignal, { once: true });
+    }
+  }
+
+  try {
+    await new Promise<void>((resolve) => {
+      if (controller.signal.aborted) {
+        resolve();
+        return;
+      }
+      controller.signal.addEventListener("abort", () => resolve(), {
+        once: true,
+      });
+    });
+    return 0;
+  } finally {
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
+    external?.removeEventListener("abort", onSignal);
+    await proxy.close().catch(() => {});
+  }
+}