@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/cli-ax.ts

@@ -1,2318 +0,0 @@
-/**
- * Agent-experience CLI commands:
- *   init / run / trajectory / eval
- *
- * Coding agents get JSON-first output, ephemeral local servers, and
- * filesystem-first evals under evals/ (*.eval.ts).
- */
-
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { Artifacts, JUnit } from "../evals/reporters.js";
-import type { EvalAssertionResult, EvalReporter, EvalRunSnapshot, EvalVerdict } from "../evals.js";
-import { serve } from "../index.js";
-import type { AgentServeHandle } from "../types.js";
-import { lookupSessionContinuation, runChat } from "./chat-client.js";
-import { ensureCursorLogin } from "./cli-cursor.js";
-import { resolveDeployAuth } from "./cli-deploy.js";
-import { resolveApiKey } from "./cursor/credentials.js";
-import {
-  type AgentkitSessionEventPoll,
-  type AgentkitSessionRuns,
-  DeployApiError,
-} from "./deploy-client.js";
-import { CLI_COMMAND_NAME, PACKAGE_NAME } from "./distribution.js";
-import {
-  discoverEvals,
-  type EvalRunResult,
-  filterDiscoveredEvals,
-  runDiscoveredEvals,
-} from "./eval-runner.js";
-import {
-  cancelRemoteEvalRun,
-  getRemoteEvalRun,
-  listRemoteEvalRuns,
-  listRemoteEvals,
-  pollRemoteEvalRun,
-  RemoteEvalError,
-  snapshotToEvalRunResults,
-  startRemoteEvalRun,
-} from "./evals-client.js";
-import { runTemplateInit, type TemplateInitSpec } from "./init-interview.js";
-import {
-  checkInitTarget,
-  formatInitNextSteps,
-  formatInitScaffoldSummary,
-  initNextCommands,
-  initProject,
-  installScaffoldDependencies,
-  linkCliOntoPath,
-  printInitGuide,
-  resolveTemplate,
-} from "./init-project.js";
-import { offerInstallCursorSkills } from "./install-cursor-skills.js";
-import { rejectV2ForLegacyCommand, v2HostedVerifyHint } from "./legacy-command-guard.js";
-import { runLogsTail, sanitizeCustomerError } from "./logs-client.js";
-import { mapPool } from "./map-pool.js";
-import { openBrowser } from "./open-browser.js";
-import { startPlaygroundProxy } from "./playground-proxy.js";
-import {
-  ProdTargetError,
-  resolveProdAliasPlaygroundUrl,
-  resolveProdPlaygroundUrl,
-  resolveProdSlug,
-  resolveProdTarget,
-} from "./resolve-prod-target.js";
-import { runSession } from "./run-client.js";
-import {
-  buildSessionCostReport,
-  formatSessionCostText,
-  formatSessionsCostText,
-  type SessionCostRow,
-} from "./session-cost.js";
-import {
-  fetchSessionEvents,
-  formatSessionsTable,
-  listSessionsWithSource,
-  resolvePreviousSessionId,
-} from "./sessions-client.js";
-import { createStreamProgress } from "./stream-progress.js";
-import {
-  buildTrajectory,
-  formatTrajectoryText,
-  loadTrajectoryFromEventsFile,
-} from "./trajectory.js";
-
-export interface AxCliOptions {
-  cwd?: string;
-  dir: string;
-  /**
-   * 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;
-  /** One or more user turns. */
-  messages?: string[];
-  sessionId?: string;
-  continuationToken?: string;
-  timeoutMs?: number;
-  /**
-   * Write raw NDJSON session events (the visualizable trace).
-   * - `true` / omitted: auto path under `<dir>/.agent-serve/traces/`
-   * - string: explicit path
-   * - `false`: skip writing
-   */
-  events?: string | true | false;
-  text?: boolean;
-  json?: boolean;
-  list?: boolean;
-  verbose?: boolean;
-  tags?: string[];
-  /** Eval ids / path prefixes. */
-  evalIds?: string[];
-  /** `eval`: a soft threshold miss (`scored`) also fails the exit code. */
-  strict?: boolean;
-  /** `eval`: write JUnit XML to this path. */
-  junit?: string;
-  /**
-   * `eval`: run-artifact directory. Defaults to a timestamped directory under
-   * `<dir>/.agent-serve/evals/`; `false` disables artifacts entirely.
-   */
-  artifacts?: string | false;
-  /** `eval`: skip reporters declared in `evals.config.ts` and eval files. */
-  skipReport?: boolean;
-  /** `eval`: override `evals.config.ts` `maxConcurrency`. */
-  maxConcurrency?: number;
-  /**
-   * `eval` / `eval status <runId>`: also write the full results JSON to this
-   * path. `session`: write the raw NDJSON trace (same format as `run
-   * --events` and the playground download) to this path instead of printing.
-   */
-  out?: string;
-  /** Scaffold target directory for `init`. */
-  initTarget?: string;
-  template?: string;
-  /** `init --var id=value` (repeatable). */
-  vars?: string[];
-  /** Tool name for `call`. */
-  toolName?: string;
-  /** JSON input for `call`. */
-  toolInput?: string;
-  /** 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`. For `eval`, this runs a server-side batch via
-   * `/v1/dev/evals/runs` (persisted when `defineStorage` has an `evals` table);
-   * without `--prod`, eval defaults to an ephemeral local harness.
-   */
-  prod?: boolean;
-  /**
-   * `eval` (`--prod` / `--url` only): start the batch via
-   * `POST /v1/dev/evals/runs` and return the `runId` without polling.
-   * Mutually exclusive with `--list`.
-   */
-  noWait?: 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;
-  /**
-   * `run --prod` / `session --prod --message`: hosted v2 session start on
-   * the agentsdk control plane. `--dry-run` marks the turn non-mutating;
-   * `--as-of` freezes the session clock at a timezone-bearing instant.
-   */
-  dryRun?: boolean;
-  asOf?: string;
-  componentKey?: string;
-}
-
-export interface ResolvedAgentTarget {
-  agentUrl: string;
-  headers?: Record<string, string>;
-  close?: () => Promise<void>;
-}
-
-function shouldStreamProgress(options: AxCliOptions): boolean {
-  if (options.stream === false) {
-    return false;
-  }
-  if (options.stream === true) {
-    return true;
-  }
-  return process.stderr.isTTY === true;
-}
-
-function die(message: string): never {
-  process.stderr.write(`${message}\n`);
-  process.exit(1);
-}
-
-function pickAgentUrl(handle: AgentServeHandle, slug?: string): string {
-  if (handle.agents.length === 0) {
-    die("No agents discovered.");
-  }
-  if (slug !== undefined && slug !== "") {
-    const match = handle.agents.find(a => a.slug === slug);
-    if (match === undefined) {
-      die(
-        `Unknown agent slug "${slug}". Available: ${handle.agents
-          .map(a => a.slug || "(root)")
-          .join(", ")}`,
-      );
-    }
-    return match.url;
-  }
-  const root = handle.agents.find(a => a.slug === "");
-  return (root ?? handle.agents[0]!).url;
-}
-
-async function startEphemeral(
-  options: AxCliOptions,
-): Promise<{ agentUrl: string; close: () => Promise<void> }> {
-  const dir = resolve(options.cwd ?? process.cwd(), options.dir);
-  const stateRoot = options.stateRoot ?? (await mkdtemp(join(tmpdir(), "agent-serve-ax-")));
-
-  const handle = await serve(dir, {
-    host: "127.0.0.1",
-    port: 0,
-    stateRoot,
-    playground: false,
-    schedules: false,
-    // Keep host/tool timing off stdout so `run`/`eval` JSON stays clean.
-    logger: (line: string) => {
-      process.stderr.write(`${line}\n`);
-    },
-    ...(options.bearerToken === undefined ? {} : { authToken: options.bearerToken }),
-  });
-
-  return {
-    agentUrl: pickAgentUrl(handle, options.slug),
-    close: async () => {
-      // engine.close() can hang on open SDK streams; don't block the CLI.
-      await Promise.race([
-        handle.close(),
-        new Promise<void>(resolve => setTimeout(resolve, 2_000)),
-      ]);
-    },
-  };
-}
-
-export async function resolveTarget(options: AxCliOptions): 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);
-}
-
-export async function cmdInit(options: AxCliOptions): Promise<number> {
-  const target = options.initTarget;
-  if (target === undefined || target === "") {
-    printInitGuide();
-    return 0;
-  }
-  let templateDir: string | undefined;
-  let overlayDir: string | undefined;
-  let templateName: string | undefined;
-  if (options.template !== undefined) {
-    const template = resolveTemplate(options.template);
-    if (!template.ok) {
-      process.stderr.write(`${template.message}\n`);
-      return 1;
-    }
-    templateDir = template.dir;
-    overlayDir = template.overlayDir;
-    templateName = template.name;
-  }
-  const cwd = options.cwd ?? process.cwd();
-  const dir = resolve(cwd, target);
-  const targetCheck = checkInitTarget(dir, options.template);
-  if (!targetCheck.ok) {
-    process.stderr.write(`${targetCheck.message}\n`);
-    return 1;
-  }
-  let answers: Record<string, string> | undefined;
-  let initSpec: TemplateInitSpec | undefined;
-  if (templateDir !== undefined) {
-    const interview = await runTemplateInit({
-      templateDir,
-      vars: options.vars,
-      interactive:
-        options.json !== true && process.stdin.isTTY === true && process.stdout.isTTY === true,
-    });
-    if (!interview.ok) {
-      process.stderr.write(`${interview.error}\n`);
-      return 1;
-    }
-    answers = interview.answers;
-    initSpec = interview.spec;
-  }
-  const result = await initProject({
-    dir,
-    templateDir,
-    overlayDir,
-    templateName,
-    answers,
-    initSpec,
-  });
-  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",
-    });
-    const linked = install.ok
-      ? await linkCliOntoPath(result.rootDir, { stdio: "pipe" })
-      : undefined;
-    const cliOnPath = linked?.ok === true;
-    process.stdout.write(
-      `${JSON.stringify(
-        {
-          ok: install.ok,
-          directory: result.rootDir,
-          template: options.template ?? null,
-          created: result.created,
-          skipped: result.skipped,
-          installed: install.ok,
-          installError: install.ok
-            ? null
-            : install.stderr.trim() || `npm install exited ${install.exitCode}`,
-          cliOnPath,
-          cliLinkError:
-            install.ok && linked !== undefined && !linked.ok
-              ? linked.stderr.trim() || `npm install -g exited ${linked.exitCode}`
-              : null,
-          next: initNextCommands({
-            rootDir: result.rootDir,
-            cwd,
-            signedIn,
-            cliOnPath,
-          }),
-        },
-        null,
-        2,
-      )}\n`,
-    );
-    return install.ok ? 0 : 1;
-  }
-
-  process.stdout.write(
-    formatInitScaffoldSummary({
-      rootDir: result.rootDir,
-      files: result.files,
-    }),
-  );
-  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 retry init.\n`,
-    );
-    return install.exitCode || 1;
-  }
-  process.stdout.write("\n");
-
-  process.stdout.write(`Installing ${CLI_COMMAND_NAME} on your PATH\n\n`);
-  const linked = await linkCliOntoPath(result.rootDir, { stdio: "inherit" });
-  const cliOnPath = linked.ok;
-  if (!cliOnPath) {
-    process.stderr.write(
-      `\nCould not put ${CLI_COMMAND_NAME} on PATH (${linked.stderr.trim() || `exit ${linked.exitCode}`}). Next steps use npx ${PACKAGE_NAME} instead.\n\n`,
-    );
-  } else {
-    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) {
-    // init always offers the browser flow (the --json path above skipped it).
-    loginExit = await ensureCursorLogin({ interactive: true });
-    signedIn = loginExit === 0 && (await resolveApiKey()) !== undefined;
-    process.stdout.write("\n");
-  }
-
-  process.stdout.write(
-    formatInitNextSteps({
-      rootDir: result.rootDir,
-      cwd,
-      signedIn,
-      cliOnPath,
-    }),
-  );
-  return loginExit;
-}
-
-/**
- * `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;
-}
-
-/**
- * `chat` — talk to a running (or `--prod` hosted) agent. With `--json`,
- * prints a trajectory instead of the interactive UI.
- */
-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> {
-  // Only a v2-shaped request tries the control plane; every v1 `run --prod`
-  // form (multi-turn, continuation token, local session id, --url) keeps its
-  // engine-alias path untouched.
-  if (options.prod === true && hostedSessionRejection(options) === undefined) {
-    const started = await cmdHostedSession(options);
-    if (started !== "fallback") {
-      return started;
-    }
-  }
-  const messages = options.messages ?? [];
-  if (messages.length === 0) {
-    die("Provide --message (repeatable) or --messages-file");
-  }
-
-  const stream = shouldStreamProgress(options);
-  const progress = stream ? createStreamProgress() : undefined;
-
-  const target = await resolveTarget(options);
-  try {
-    if (stream) {
-      process.stderr.write(`→ ${target.agentUrl}\n`);
-    }
-    const result = await runSession({
-      baseUrl: target.agentUrl,
-      messages,
-      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;
-    const writeEvents = options.events !== false;
-    if (writeEvents) {
-      if (typeof options.events === "string") {
-        eventsPath = resolve(options.events);
-      } else {
-        const root = resolve(options.cwd ?? process.cwd(), options.dir);
-        const tracesDir = join(root, ".agent-serve", "traces");
-        await mkdir(tracesDir, { recursive: true });
-        eventsPath = join(tracesDir, `${result.sessionId}.ndjson`);
-      }
-      await writeFile(
-        eventsPath,
-        `${result.events.map(e => JSON.stringify(e)).join("\n")}\n`,
-        "utf8",
-      );
-    }
-
-    const playgroundUrl =
-      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) {
-      process.stdout.write(formatTrajectoryText(result.trajectory));
-      if (eventsPath !== undefined) {
-        process.stderr.write(`\ntrace: ${eventsPath}\n`);
-      }
-      if (playgroundUrl !== null) {
-        process.stderr.write(`playground: ${playgroundUrl}\n`);
-      } else if (playgroundHint !== null) {
-        process.stderr.write(`playground: ${playgroundHint}\n`);
-      }
-    } else {
-      console.log(
-        JSON.stringify(
-          {
-            ok: result.ok,
-            sessionId: result.sessionId,
-            continuationToken: result.continuationToken ?? null,
-            trace: eventsPath ?? null,
-            playgroundUrl,
-            playgroundHint,
-            visualize:
-              playgroundHint !== null
-                ? `Run ${playgroundHint}`
-                : playgroundUrl !== null
-                  ? `Open ${playgroundUrl}`
-                  : eventsPath !== undefined
-                    ? `${CLI_COMMAND_NAME} trajectory --events ${eventsPath}`
-                    : null,
-            trajectory: result.trajectory,
-          },
-          null,
-          2,
-        ),
-      );
-    }
-    return result.ok ? 0 : 1;
-  } finally {
-    progress?.close();
-    if (target.close !== undefined) {
-      await target.close();
-    }
-  }
-}
-
-const HOSTED_SESSION_ID_RE = /^ses_[a-f0-9]{24}$/;
-
-/**
- * Hosted v2 session start: POST the agentsdk control plane, which hands the
- * wake to Temporal (no resident engine, no `/engine/*` alias). `--session
- * ses_…` resumes that exact session; there is no continuation token on
- * this path. A 404 means the slug is not a v2 control-plane deployment, so
- * `run --prod` falls back to the v1 engine alias.
- */
-/** Why these options cannot be a hosted v2 session start, if they cannot. */
-function hostedSessionRejection(options: AxCliOptions): string | undefined {
-  if (options.url !== undefined) {
-    return "--prod session start talks to the agentsdk control plane; do not pass --url";
-  }
-  const messages = options.messages ?? [];
-  if (messages.length !== 1 || messages[0]?.trim() === "") {
-    return "Provide exactly one --message (the wake). Multi-turn runs are local-only.";
-  }
-  if (trimNonEmpty(options.continuationToken) !== undefined) {
-    return "--continuation-token is not a hosted v2 identity; pass --session ses_… to resume a session";
-  }
-  const sessionId = trimNonEmpty(options.sessionId);
-  if (sessionId !== undefined && !HOSTED_SESSION_ID_RE.test(sessionId)) {
-    return `--session must be a hosted session id (ses_…), got ${sessionId}`;
-  }
-  return undefined;
-}
-
-async function cmdHostedSession(options: AxCliOptions): Promise<number | "fallback"> {
-  const rejection = hostedSessionRejection(options);
-  if (rejection !== undefined) {
-    die(rejection);
-  }
-  const messages = options.messages ?? [];
-  const sessionId = trimNonEmpty(options.sessionId);
-  const auth = await resolveDeployAuth({
-    team: options.team,
-    apiKey: options.apiKey,
-    fetchImpl: options.fetchImpl,
-  });
-  if (typeof auth === "number") {
-    return auth;
-  }
-  const slug = resolveProdSlug(options);
-  try {
-    const accepted = await auth.client.startSession({
-      teamId: auth.teamId,
-      slug,
-      message: messages[0]!.trim(),
-      sessionId,
-      dryRun: options.dryRun,
-      asOf: options.asOf,
-      componentKey: trimNonEmpty(options.componentKey),
-    });
-    console.log(JSON.stringify(accepted, null, 2));
-    if (accepted.sessionId === undefined) {
-      process.stderr.write(`${v2HostedVerifyHint(slug)}\n`);
-    }
-    return 0;
-  } catch (error) {
-    if (error instanceof DeployApiError && error.status === 404) {
-      return "fallback";
-    }
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    return 1;
-  }
-}
-
-/**
- * Shared deterministic-route fetch (`call`, `skill`): engine headers,
- * bearer auth, and JSON. The payload is `undefined` when the body does
- * not decode; callers print `invalid_response` and fail.
- */
-async function fetchAgentJson(
-  target: ResolvedAgentTarget,
-  path: string,
-  args: { method?: string; body?: string; bearerToken?: string } = {},
-): Promise<{ response: Response; payload: unknown }> {
-  const headers: Record<string, string> = {};
-  if (target.headers !== undefined) {
-    Object.assign(headers, target.headers);
-  }
-  if (args.body !== undefined) {
-    headers["content-type"] = "application/json";
-  }
-  if (args.bearerToken !== undefined) {
-    headers.authorization = `Bearer ${args.bearerToken}`;
-  }
-  const response = await fetch(`${target.agentUrl}${path}`, {
-    method: args.method,
-    headers,
-    body: args.body,
-  });
-  const payload: unknown = await response.json().catch(() => undefined);
-  return { response, payload };
-}
-
-function printInvalidResponse(): void {
-  console.log(JSON.stringify({ ok: false, error: "invalid_response" }, null, 2));
-}
-
-/**
- * `agent-sdk call <tool>` — deterministic tool invocation over
- * `POST /v1/tools/:toolName` (ephemeral local server unless --url).
- */
-export async function cmdCall(options: AxCliOptions): Promise<number> {
-  const toolName = options.toolName;
-  if (toolName === undefined || toolName === "") {
-    die(`Provide a tool name: ${CLI_COMMAND_NAME} call <tool> [--input '{...}']`);
-  }
-  let input: unknown = {};
-  if (options.toolInput !== undefined) {
-    try {
-      input = JSON.parse(options.toolInput);
-    } catch (error) {
-      die(`--input must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  let target: ResolvedAgentTarget;
-  try {
-    target = await resolveTarget(options);
-  } catch (error) {
-    process.stderr.write(
-      `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n`,
-    );
-    return 1;
-  }
-  try {
-    const body: { input: unknown; sessionId?: string } = { input };
-    if (options.sessionId !== undefined) {
-      body.sessionId = options.sessionId;
-    }
-    const { response, payload } = await fetchAgentJson(
-      target,
-      `/v1/tools/${encodeURIComponent(toolName)}`,
-      {
-        method: "POST",
-        body: JSON.stringify(body),
-        bearerToken: options.bearerToken,
-      },
-    );
-    if (payload === undefined) {
-      printInvalidResponse();
-      return 1;
-    }
-    console.log(JSON.stringify(payload, null, 2));
-    const ok =
-      response.ok &&
-      typeof payload === "object" &&
-      payload !== null &&
-      (payload as { ok?: unknown }).ok === true;
-    return ok ? 0 : 1;
-  } finally {
-    if (target.close !== undefined) {
-      await target.close();
-    }
-  }
-}
-
-/**
- * `agent-sdk skill <name>` — deterministic skill read over
- * `GET /v1/skills/:skillName` (ephemeral local server unless --url).
- * `--text` prints the rendered SKILL.md instead of JSON.
- */
-export async function cmdSkill(
-  skillName: string | undefined,
-  options: AxCliOptions,
-): Promise<number> {
-  if (skillName === undefined || skillName === "") {
-    process.stderr.write(
-      `Usage: ${CLI_COMMAND_NAME} skill <name> [--dir <path> | --url <baseUrl> | --prod]\n`,
-    );
-    return 2;
-  }
-
-  const target = await resolveTarget(options);
-  try {
-    const { response, payload } = await fetchAgentJson(
-      target,
-      `/v1/skills/${encodeURIComponent(skillName)}`,
-      { bearerToken: options.bearerToken },
-    );
-    if (payload === undefined) {
-      printInvalidResponse();
-      return 1;
-    }
-    if (options.text === true && response.ok) {
-      const skillMd = (payload as { skillMd?: unknown }).skillMd;
-      if (typeof skillMd !== "string") {
-        printInvalidResponse();
-        return 1;
-      }
-      process.stdout.write(skillMd.endsWith("\n") ? skillMd : `${skillMd}\n`);
-      return 0;
-    }
-    console.log(JSON.stringify(payload, null, 2));
-    return response.ok ? 0 : 1;
-  } finally {
-    if (target.close !== undefined) {
-      await target.close();
-    }
-  }
-}
-
-export async function cmdTrajectory(options: AxCliOptions): Promise<number> {
-  if (typeof options.events !== "string") {
-    die(
-      `trajectory requires --events <file.ndjson> (write one with: ${CLI_COMMAND_NAME} run --events …)`,
-    );
-  }
-  const trajectory = await loadTrajectoryFromEventsFile(resolve(options.events));
-  if (options.text) {
-    process.stdout.write(formatTrajectoryText(trajectory));
-  } else {
-    console.log(JSON.stringify(trajectory, null, 2));
-  }
-  return trajectory.ok ? 0 : 1;
-}
-
-/**
- * Which surface `eval` should target. Local (ephemeral) is the default;
- * `--prod` uses the hosted deployment, `--url` a running server.
- * Exported for tests.
- */
-export function resolveEvalTargetMode(
-  options: Pick<AxCliOptions, "prod" | "url">,
-): "local" | "url" | "deployment" | { error: string } {
-  const flags = [
-    options.prod === true ? "--prod" : undefined,
-    options.url !== undefined ? "--url" : undefined,
-  ].filter(flag => flag !== undefined);
-  if (flags.length > 1) {
-    return { error: `${flags.join(" and ")} are mutually exclusive` };
-  }
-  if (options.url !== undefined) {
-    return "url";
-  }
-  if (options.prod === true) {
-    return "deployment";
-  }
-  return "local";
-}
-
-/** Resolve the eval target; prints a CLI-ready error and returns an exit code on failure. */
-async function resolveEvalTarget(options: AxCliOptions): Promise<ResolvedAgentTarget | number> {
-  const mode = resolveEvalTargetMode(options);
-  if (typeof mode === "object") {
-    process.stderr.write(`${mode.error}\n`);
-    return 2;
-  }
-  if (mode === "url") {
-    return { agentUrl: options.url!.replace(/\/$/, "") };
-  }
-  if (mode === "local") {
-    return startEphemeral(options);
-  }
-  try {
-    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 };
-  } catch (error) {
-    if (error instanceof ProdTargetError && error.notFound) {
-      // Keep the API error text: a 404 can also mean a wrong API host or a
-      // disabled feature gate, and the message distinguishes those from a
-      // genuinely missing deployment.
-      process.stderr.write(
-        `${sanitizeCustomerError(error.message)}\n` +
-          `  deploy it first:  ${CLI_COMMAND_NAME} deploy --slug ${error.slug}\n` +
-          `  or omit --prod:   ${CLI_COMMAND_NAME} eval --dir ${options.dir}\n`,
-      );
-      return 1;
-    }
-    process.stderr.write(
-      `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n` +
-        `Pass --prod for the hosted deployment, or omit it to run on an ephemeral local server.\n`,
-    );
-    return 1;
-  }
-}
-
-export async function cmdEval(options: AxCliOptions): Promise<number> {
-  const projectRoot = resolve(options.cwd ?? process.cwd(), options.dir);
-  const mode = resolveEvalTargetMode(options);
-  if (typeof mode === "object") {
-    process.stderr.write(`${mode.error}\n`);
-    return 2;
-  }
-  if (options.noWait === true) {
-    if (options.list === true) {
-      process.stderr.write("--no-wait and --list are mutually exclusive\n");
-      return 2;
-    }
-    if (mode === "local") {
-      process.stderr.write("--no-wait requires --prod or --url (not the default local target)\n");
-      return 2;
-    }
-  }
-  if (trimNonEmpty(options.out) !== undefined) {
-    if (options.list === true) {
-      process.stderr.write("--out and --list are mutually exclusive\n");
-      return 2;
-    }
-    if (options.noWait === true) {
-      process.stderr.write(
-        `--out needs the finished results; drop --no-wait, or poll later with ${CLI_COMMAND_NAME} eval status <evalId> --out <path>\n`,
-      );
-      return 2;
-    }
-  }
-
-  const filterIds =
-    options.evalIds === undefined || options.evalIds.length === 0 ? undefined : options.evalIds;
-  const tags = options.tags === undefined || options.tags.length === 0 ? undefined : options.tags;
-
-  if (options.list) {
-    // List the same surface a run will execute: local filesystem by default,
-    // GET /v1/dev/evals on --prod / --url.
-    if (mode === "local") {
-      return listLocalEvals(projectRoot, options, filterIds, tags);
-    }
-    const target = await resolveEvalTarget(options);
-    if (typeof target === "number") {
-      return target;
-    }
-    try {
-      const listed = await listRemoteEvals({
-        baseUrl: target.agentUrl,
-        auth: {
-          bearerToken: options.bearerToken,
-          headers: target.headers,
-        },
-        fetchImpl: options.fetchImpl,
-        filterIds,
-        tags,
-      });
-      return printListedEvals(
-        listed.map(e => ({
-          id: e.id,
-          fileId: e.fileId,
-          description: e.description,
-          tags: e.tags ?? [],
-        })),
-        options,
-        `No evals on ${target.agentUrl}`,
-      );
-    } catch (error) {
-      process.stderr.write(
-        `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n`,
-      );
-      return 1;
-    } finally {
-      if (target.close !== undefined) {
-        await target.close();
-      }
-    }
-  }
-
-  const target = await resolveEvalTarget(options);
-  if (typeof target === "number") {
-    return target;
-  }
-  const stream = shouldStreamProgress(options);
-
-  try {
-    if (options.verbose || stream) {
-      process.stderr.write(`eval target: ${target.agentUrl}\n`);
-    }
-
-    // Default local: ephemeral in-process harness against local eval sources.
-    // --prod / --url: run on the serve process via /v1/dev/evals/runs so the
-    // batch lands in playground history and defineStorage evals (when set).
-    if (mode === "local") {
-      const progress = stream ? createStreamProgress() : undefined;
-      const artifactsDir = resolveEvalArtifactsDir(projectRoot, options);
-      try {
-        const results = await runDiscoveredEvals({
-          projectRoot,
-          baseUrl: target.agentUrl,
-          filterIds,
-          tags,
-          timeoutMs: options.timeoutMs,
-          maxConcurrency: options.maxConcurrency,
-          strict: options.strict === true,
-          skipReport: options.skipReport === true,
-          reporters: buildCliEvalReporters(options, artifactsDir),
-          target: { baseUrl: target.agentUrl, mode: "local" },
-          bearerToken: options.bearerToken,
-          headers: target.headers,
-          verbose: Boolean(options.verbose) || stream,
-          onEvent: progress === undefined ? undefined : e => progress.onEvent(e),
-        });
-        if (results.length === 0) {
-          process.stderr.write("No matching evals found.\n");
-          return 2;
-        }
-        return await printEvalResults(results, options, undefined, artifactsDir);
-      } finally {
-        progress?.close();
-      }
-    }
-
-    try {
-      if (options.noWait === true) {
-        const started = await startRemoteEvalRun({
-          baseUrl: target.agentUrl,
-          filterIds,
-          tags,
-          timeoutMs: options.timeoutMs,
-          verbose: Boolean(options.verbose),
-          auth: {
-            bearerToken: options.bearerToken,
-            headers: target.headers,
-          },
-          fetchImpl: options.fetchImpl,
-        });
-        return await printEvalAccepted(started, options, target.agentUrl);
-      }
-
-      const progress = createRemoteEvalProgress(options.verbose === true || stream);
-      // Start first so we can print the Eval ID before the (often long) wait.
-      const started = await startRemoteEvalRun({
-        baseUrl: target.agentUrl,
-        filterIds,
-        tags,
-        timeoutMs: options.timeoutMs,
-        verbose: Boolean(options.verbose) || stream,
-        auth: {
-          bearerToken: options.bearerToken,
-          headers: target.headers,
-        },
-        fetchImpl: options.fetchImpl,
-      });
-      await printEvalIdBanner(started, options, target.agentUrl);
-      progress?.onSnapshot?.(started);
-      const snapshot = await pollRemoteEvalRun({
-        baseUrl: target.agentUrl,
-        runId: started.runId,
-        auth: {
-          bearerToken: options.bearerToken,
-          headers: target.headers,
-        },
-        fetchImpl: options.fetchImpl,
-        onSnapshot: progress === undefined ? undefined : progress.onSnapshot,
-      });
-      const results = snapshotToEvalRunResults(snapshot);
-      if (results.length === 0 && snapshot.status !== "failed") {
-        process.stderr.write("No matching evals found.\n");
-        return 2;
-      }
-      return await printEvalResults(results, options, {
-        runId: snapshot.runId,
-        status: snapshot.status,
-        error: snapshot.error,
-      });
-    } catch (error) {
-      if (error instanceof RemoteEvalError && error.code === "no_matching_evals") {
-        process.stderr.write(`${error.message}\n`);
-        return 2;
-      }
-      process.stderr.write(
-        `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n`,
-      );
-      return 1;
-    }
-  } finally {
-    if (target.close !== undefined) {
-      await target.close();
-    }
-  }
-}
-
-/**
- * Flags to re-target the same surface from an `eval --no-wait` hint.
- * Exported for tests.
- */
-export function formatEvalStatusFlags(
-  options: Pick<AxCliOptions, "prod" | "url" | "slug" | "team">,
-): string {
-  const parts: string[] = [];
-  if (options.url !== undefined) {
-    parts.push(`--url ${options.url.replace(/\/$/, "")}`);
-  } else {
-    parts.push("--prod");
-    if (options.slug !== undefined && options.slug !== "") {
-      parts.push(`--slug ${options.slug}`);
-    }
-  }
-  if (options.team !== undefined && options.team !== "") {
-    parts.push(`--team ${options.team}`);
-  }
-  return parts.length === 0 ? "" : ` ${parts.join(" ")}`;
-}
-
-/** Print Eval ID + cancel/status hints after a remote batch is accepted. */
-async function printEvalIdBanner(
-  started: EvalRunSnapshot,
-  options: AxCliOptions,
-  agentUrl: string,
-): Promise<void> {
-  const pollPath = `${agentUrl.replace(/\/$/, "")}/v1/dev/evals/runs/${started.runId}`;
-  const statusFlags = formatEvalStatusFlags(options);
-  const playgroundUrl = await resolveEvalPlaygroundDeepLink(options, started.runId, agentUrl);
-  if (options.json) {
-    // Waiters still want the id on stderr so progress text stays readable.
-    process.stderr.write(
-      `${JSON.stringify({
-        evalId: started.runId,
-        runId: started.runId,
-        status: started.status,
-        summary: started.summary,
-        pollUrl: pollPath,
-        ...(playgroundUrl === undefined ? {} : { playgroundUrl }),
-      })}\n`,
-    );
-    return;
-  }
-  const durable = started.config.durableRuns === true ? " (persisted)" : "";
-  process.stderr.write(`Eval ID: ${started.runId}${durable} — ${started.summary.total} case(s)\n`);
-  process.stderr.write(`Cancel:  ${CLI_COMMAND_NAME} eval cancel ${started.runId}${statusFlags}\n`);
-  process.stderr.write(`Status:  ${CLI_COMMAND_NAME} eval status ${started.runId}${statusFlags}\n`);
-  if (playgroundUrl !== undefined) {
-    process.stderr.write(`Playground: ${playgroundUrl}\n`);
-  }
-}
-
-/** `--no-wait`: print the accepted batch id (and how to poll) then exit. */
-async function printEvalAccepted(
-  started: EvalRunSnapshot,
-  options: AxCliOptions,
-  agentUrl: string,
-): Promise<number> {
-  const pollPath = `${agentUrl.replace(/\/$/, "")}/v1/dev/evals/runs/${started.runId}`;
-  const statusFlags = formatEvalStatusFlags(options);
-  const playgroundUrl = await resolveEvalPlaygroundDeepLink(options, started.runId, agentUrl);
-  if (options.json) {
-    process.stdout.write(
-      `${JSON.stringify(
-        {
-          ok: true,
-          accepted: true,
-          evalId: started.runId,
-          runId: started.runId,
-          status: started.status,
-          summary: started.summary,
-          pollUrl: pollPath,
-          durableRuns: started.config.durableRuns === true,
-          ...(playgroundUrl === undefined ? {} : { playgroundUrl }),
-        },
-        null,
-        2,
-      )}\n`,
-    );
-  } else {
-    const durable = started.config.durableRuns === true ? " (persisted)" : "";
-    process.stdout.write(
-      `Eval ID: ${started.runId}${durable} — ${started.summary.total} case(s)\n`,
-    );
-    process.stdout.write(
-      `Cancel:  ${CLI_COMMAND_NAME} eval cancel ${started.runId}${statusFlags}\n`,
-    );
-    process.stdout.write(
-      `Status:  ${CLI_COMMAND_NAME} eval status ${started.runId}${statusFlags}\n`,
-    );
-    if (playgroundUrl !== undefined) {
-      process.stdout.write(`Playground: ${playgroundUrl}\n`);
-    }
-    process.stdout.write(`Poll: ${pollPath}\n`);
-  }
-  return 0;
-}
-
-/**
- * Hosted alias playground URL with `view=evals` + `evalRunId` so the SPA
- * opens the batch that CLI / Slack started (not a stale sessionStorage id).
- */
-async function resolveEvalPlaygroundDeepLink(
-  options: AxCliOptions,
-  runId: string,
-  agentUrl: string,
-): Promise<string | undefined> {
-  if (options.prod !== true) {
-    const base = `${agentUrl.replace(/\/$/, "")}/playground`;
-    try {
-      const url = new URL(base);
-      url.searchParams.set("view", "evals");
-      url.searchParams.set("evalRunId", runId);
-      return url.toString();
-    } catch {
-      return undefined;
-    }
-  }
-  try {
-    const resolved = await resolveProdAliasPlaygroundUrl({
-      dir: options.dir,
-      cwd: options.cwd,
-      slug: options.slug,
-      team: options.team,
-      apiKey: options.apiKey,
-      fetchImpl: options.fetchImpl,
-      // Avoid a second "Using hosted deployment" line; banner already has context.
-      err: () => {},
-    });
-    const url = new URL(resolved.playgroundUrl);
-    url.searchParams.set("view", "evals");
-    url.searchParams.set("evalRunId", runId);
-    return url.toString();
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * `eval cancel <runId>` — cancel a running remote batch by Eval ID.
- */
-export async function cmdEvalCancel(
-  runId: string | undefined,
-  options: AxCliOptions,
-): Promise<number> {
-  const mode = resolveEvalTargetMode(options);
-  if (typeof mode === "object") {
-    process.stderr.write(`${mode.error}\n`);
-    return 2;
-  }
-  if (mode === "local") {
-    process.stderr.write("eval cancel requires --prod or --url (not the default local target)\n");
-    return 2;
-  }
-  if (runId === undefined || runId === "") {
-    process.stderr.write("usage: eval cancel <evalId> --prod|--url …\n");
-    return 2;
-  }
-  if (options.list === true || options.noWait === true) {
-    process.stderr.write("eval cancel does not accept --list or --no-wait\n");
-    return 2;
-  }
-
-  const target = await resolveEvalTarget(options);
-  if (typeof target === "number") {
-    return target;
-  }
-
-  try {
-    const snap = await cancelRemoteEvalRun({
-      baseUrl: target.agentUrl,
-      runId,
-      auth: {
-        bearerToken: options.bearerToken,
-        headers: target.headers,
-      },
-      fetchImpl: options.fetchImpl,
-    });
-    if (options.json) {
-      process.stdout.write(`${JSON.stringify(snap, null, 2)}\n`);
-    } else {
-      process.stdout.write(
-        `Cancelled Eval ID ${snap.runId} (${snap.summary.done}/${snap.summary.total} cases finalized)\n`,
-      );
-    }
-    return 0;
-  } catch (error) {
-    process.stderr.write(
-      `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n`,
-    );
-    return 1;
-  } finally {
-    if (target.close !== undefined) {
-      await target.close();
-    }
-  }
-}
-
-/**
- * `eval status [runId]` — fetch one batch (or list recent) on the deployment /
- * `--url` target. Exit `0` when the batch is completed with all cases passing,
- * `1` when failed / any case failed / unknown, `2` for usage errors, `3` when
- * the batch is still running (for poll loops after `--no-wait`).
- */
-export async function cmdEvalStatus(
-  runId: string | undefined,
-  options: AxCliOptions,
-): Promise<number> {
-  const mode = resolveEvalTargetMode(options);
-  if (typeof mode === "object") {
-    process.stderr.write(`${mode.error}\n`);
-    return 2;
-  }
-  if (mode === "local") {
-    process.stderr.write("eval status requires --prod or --url (not the default local target)\n");
-    return 2;
-  }
-  if (options.list === true || options.noWait === true) {
-    process.stderr.write("eval status does not accept --list or --no-wait\n");
-    return 2;
-  }
-  if (trimNonEmpty(options.out) !== undefined && (runId === undefined || runId === "")) {
-    process.stderr.write("eval status --out requires an eval id\n");
-    return 2;
-  }
-
-  const target = await resolveEvalTarget(options);
-  if (typeof target === "number") {
-    return target;
-  }
-  const auth = {
-    bearerToken: options.bearerToken,
-    headers: target.headers,
-  };
-
-  try {
-    if (runId === undefined || runId === "") {
-      const { runs, activeRunId } = await listRemoteEvalRuns({
-        baseUrl: target.agentUrl,
-        auth,
-        fetchImpl: options.fetchImpl,
-      });
-      if (options.json) {
-        process.stdout.write(`${JSON.stringify({ runs, activeRunId }, null, 2)}\n`);
-      } else if (runs.length === 0) {
-        process.stdout.write("No eval runs on this agent.\n");
-      } else {
-        if (activeRunId !== undefined) {
-          process.stdout.write(`active: ${activeRunId}\n`);
-        }
-        for (const run of runs) {
-          process.stdout.write(`${formatEvalRunSummaryLine(run)}\n`);
-        }
-      }
-      return 0;
-    }
-
-    const snap = await getRemoteEvalRun({
-      baseUrl: target.agentUrl,
-      runId,
-      auth,
-      fetchImpl: options.fetchImpl,
-    });
-    const outPath = await writeJsonOutFile(options.out, snap);
-    if (options.json) {
-      process.stdout.write(`${JSON.stringify(snap, null, 2)}\n`);
-      if (outPath !== undefined) {
-        process.stderr.write(`results: ${outPath}\n`);
-      }
-    } else {
-      process.stdout.write(`${formatEvalRunSummaryLine(snap)}\n`);
-      if (snap.error !== undefined && snap.error !== "") {
-        process.stdout.write(`error: ${snap.error}\n`);
-      }
-      for (const c of snap.cases) {
-        const mark = c.status !== "done" ? c.status : c.ok === true ? "PASS" : "FAIL";
-        const dur = c.durationMs === undefined ? "" : ` (${(c.durationMs / 1000).toFixed(1)}s)`;
-        process.stdout.write(`  ${mark}  ${c.id}${dur}\n`);
-        if (c.error !== undefined && c.error !== "") {
-          process.stdout.write(`    error: ${c.error}\n`);
-        }
-      }
-      if (outPath !== undefined) {
-        process.stdout.write(`results: ${outPath}\n`);
-      }
-    }
-    if (snap.status === "running") {
-      return 3;
-    }
-    const failed =
-      snap.status === "failed" ||
-      snap.status === "cancelled" ||
-      snap.cases.some(c => c.ok !== true);
-    return failed ? 1 : 0;
-  } catch (error) {
-    process.stderr.write(
-      `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n`,
-    );
-    return 1;
-  } finally {
-    if (target.close !== undefined) {
-      await target.close();
-    }
-  }
-}
-
-function formatEvalRunSummaryLine(run: EvalRunSnapshot): string {
-  const { passed, failed, total, done } = run.summary;
-  const durable = run.config.durableRuns === true ? " persisted" : "";
-  return `${run.runId}  ${run.status}  ${done}/${total} done (${passed} passed, ${failed} failed)${durable}`;
-}
-
-async function listLocalEvals(
-  projectRoot: string,
-  options: AxCliOptions,
-  filterIds: string[] | undefined,
-  tags: string[] | undefined,
-): Promise<number> {
-  const { evals } = await discoverEvals(projectRoot);
-  const listed = filterDiscoveredEvals(evals, { filterIds, tags });
-  return printListedEvals(
-    listed.map(e => ({
-      id: e.id,
-      fileId: e.fileId,
-      path: e.path,
-      description: e.definition.description,
-      tags: e.definition.tags ?? [],
-    })),
-    options,
-    `No evals under ${projectRoot}/evals`,
-  );
-}
-
-function printListedEvals(
-  listed: Array<{
-    id: string;
-    fileId: string;
-    path?: string;
-    description?: string;
-    tags: string[];
-  }>,
-  options: AxCliOptions,
-  emptyMessage: string,
-): number {
-  if (options.json) {
-    process.stdout.write(`${JSON.stringify(listed, null, 2)}\n`);
-  } else if (listed.length === 0) {
-    process.stdout.write(`${emptyMessage}\n`);
-  } else {
-    for (const e of listed) {
-      const tagSuffix = e.tags.length > 0 ? `  [${e.tags.join(", ")}]` : "";
-      const desc = e.description !== undefined ? ` — ${e.description}` : "";
-      process.stdout.write(`${e.id}${tagSuffix}${desc}\n`);
-    }
-  }
-  return 0;
-}
-
-/**
- * Remote batches don't stream turn events to the CLI; print run/case progress
- * (and case logs once they appear on the snapshot) instead.
- */
-function createRemoteEvalProgress(
-  enabled: boolean,
-): { onSnapshot: (snap: EvalRunSnapshot) => void } | undefined {
-  if (!enabled) {
-    return undefined;
-  }
-  let lastSummaryKey = "";
-  const seenCaseKeys = new Set<string>();
-  return {
-    onSnapshot(snap) {
-      // Eval ID is printed by printEvalIdBanner / printEvalAccepted.
-      const summaryKey = `${snap.status}:${snap.summary.done}:${snap.summary.passed}:${snap.summary.failed}`;
-      if (summaryKey !== lastSummaryKey) {
-        lastSummaryKey = summaryKey;
-        const { done, total, passed, failed } = snap.summary;
-        process.stderr.write(
-          `eval progress: ${done}/${total} done (${passed} passed, ${failed} failed) [${snap.status}]\n`,
-        );
-      }
-      for (const c of snap.cases) {
-        if (c.status !== "done") {
-          continue;
-        }
-        const caseKey = `${c.id}:${c.ok === true ? "pass" : "fail"}:${c.durationMs ?? 0}`;
-        if (seenCaseKeys.has(caseKey)) {
-          continue;
-        }
-        seenCaseKeys.add(caseKey);
-        process.stderr.write(
-          `  eval ${c.id}: ${c.ok === true ? "PASS" : "FAIL"}${
-            c.error !== undefined ? ` — ${c.error}` : ""
-          }\n`,
-        );
-        for (const line of c.logs ?? []) {
-          process.stderr.write(`    ${line}\n`);
-        }
-      }
-    },
-  };
-}
-
-/**
- * Where a local run writes its artifacts.
- *
- * Defaults to a timestamped directory under the project's gitignored
- * `.agent-serve/evals/`, so the full story of a failure is always on disk
- * without the eval author opting in. `--no-artifacts` turns it off.
- */
-export function resolveEvalArtifactsDir(
-  projectRoot: string,
-  options: Pick<AxCliOptions, "artifacts">,
-): string | undefined {
-  if (options.artifacts === false) {
-    return undefined;
-  }
-  if (typeof options.artifacts === "string" && options.artifacts !== "") {
-    return resolve(options.artifacts);
-  }
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  return join(projectRoot, ".agent-serve", "evals", stamp);
-}
-
-/** JUnit / artifacts reporters requested via CLI flags. */
-function buildCliEvalReporters(
-  options: AxCliOptions,
-  artifactsDir: string | undefined,
-): EvalReporter[] {
-  const reporters: EvalReporter[] = [];
-  if (artifactsDir !== undefined) {
-    reporters.push(Artifacts({ dir: artifactsDir }));
-  }
-  if (options.junit !== undefined && options.junit !== "") {
-    reporters.push(JUnit({ filePath: options.junit }));
-  }
-  return reporters;
-}
-
-function evalVerdictOf(result: EvalRunResult): EvalVerdict {
-  return result.verdict ?? (result.ok ? "passed" : "failed");
-}
-
-const EVAL_VERDICT_LABEL: Record<EvalVerdict, string> = {
-  passed: "PASS",
-  failed: "FAIL",
-  scored: "SCORED",
-  skipped: "SKIP",
-};
-
-async function printEvalResults(
-  results: EvalRunResult[],
-  options: AxCliOptions,
-  batch?: {
-    runId?: string;
-    status?: EvalRunSnapshot["status"];
-    error?: string;
-  },
-  artifactsDir?: string,
-): Promise<number> {
-  const strict = options.strict === true;
-  const counts = { passed: 0, failed: 0, scored: 0, skipped: 0 };
-  for (const result of results) {
-    counts[evalVerdictOf(result)]++;
-  }
-  const batchFailed = batch?.status === "failed";
-  const ok = counts.failed === 0 && !(strict && counts.scored > 0) && !batchFailed;
-
-  if (batch?.error !== undefined && batch.error !== "" && !options.json) {
-    // Always surface harness-level failures (not only --verbose).
-    process.stderr.write(`eval run error: ${batch.error}\n`);
-  }
-
-  const payload = {
-    ok,
-    passed: counts.passed,
-    failed: counts.failed,
-    scored: counts.scored,
-    skipped: counts.skipped,
-    strict,
-    results,
-    ...(artifactsDir === undefined ? {} : { artifactsDir }),
-    ...(batch?.runId === undefined ? {} : { runId: batch.runId }),
-    ...(batch?.status === undefined ? {} : { status: batch.status }),
-    ...(batch?.error === undefined || batch.error === "" ? {} : { error: batch.error }),
-  };
-  const outPath = await writeJsonOutFile(options.out, payload);
-
-  if (options.json) {
-    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
-    if (outPath !== undefined) {
-      // stdout stays pure JSON; report the file on stderr.
-      process.stderr.write(`results: ${outPath}\n`);
-    }
-  } else {
-    for (const r of results) {
-      const verdict = evalVerdictOf(r);
-      process.stdout.write(
-        `${EVAL_VERDICT_LABEL[verdict]}  ${r.id} (${(r.durationMs / 1000).toFixed(1)}s)`,
-      );
-      if (r.description !== undefined) {
-        process.stdout.write(` — ${r.description}`);
-      }
-      process.stdout.write("\n");
-      if (r.skipReason !== undefined) {
-        process.stdout.write(`  skipped: ${r.skipReason}\n`);
-      }
-      for (const a of r.assertions) {
-        process.stdout.write(`  ${formatEvalAssertionLine(a)}\n`);
-      }
-      for (const [name, value] of Object.entries(r.metrics ?? {})) {
-        process.stdout.write(`  metric ${name}=${String(value)}\n`);
-      }
-      for (const line of r.logs ?? []) {
-        process.stdout.write(`  ${line}\n`);
-      }
-      if (r.error !== undefined) {
-        process.stdout.write(`  error: ${r.error}\n`);
-      }
-      if (options.verbose && r.finalText !== undefined) {
-        process.stdout.write(`  reply: ${r.finalText.slice(0, 200).replace(/\s+/g, " ")}\n`);
-      }
-    }
-    const extra: string[] = [];
-    if (counts.scored > 0) {
-      extra.push(`${counts.scored} scored${strict ? " (fatal: --strict)" : ""}`);
-    }
-    if (counts.skipped > 0) {
-      extra.push(`${counts.skipped} skipped`);
-    }
-    process.stdout.write(
-      `\n${counts.passed} passed, ${counts.failed} failed${
-        extra.length === 0 ? "" : `, ${extra.join(", ")}`
-      }, ${results.length} total\n`,
-    );
-    if (artifactsDir !== undefined) {
-      process.stdout.write(`artifacts: ${artifactsDir}\n`);
-    }
-    if (outPath !== undefined) {
-      process.stdout.write(`results: ${outPath}\n`);
-    }
-  }
-  return ok ? 0 : 1;
-}
-
-/**
- * `--out <path>`: write a JSON payload (results / run snapshot), creating
- * parent directories. Returns the resolved path, or undefined when unset.
- */
-async function writeJsonOutFile(
-  out: string | undefined,
-  payload: unknown,
-): Promise<string | undefined> {
-  const trimmed = trimNonEmpty(out);
-  if (trimmed === undefined) {
-    return undefined;
-  }
-  const target = resolve(trimmed);
-  await mkdir(dirname(target), { recursive: true });
-  await writeFile(target, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-  return target;
-}
-
-/**
- * One assertion line. Soft assertions read `~` rather than `✗` when they miss,
- * so a tracked score is visibly different from a failed gate.
- */
-export function formatEvalAssertionLine(assertion: EvalAssertionResult): string {
-  const soft = (assertion.severity ?? "gate") === "soft";
-  const mark = assertion.passed ? "✓" : soft ? "~" : "✗";
-  const parts: string[] = [];
-  if (assertion.score !== undefined) {
-    parts.push(
-      `score=${assertion.score.toFixed(3)}${
-        assertion.threshold === undefined ? "" : ` >= ${assertion.threshold}`
-      }`,
-    );
-  }
-  if (assertion.detail !== undefined) {
-    parts.push(assertion.detail);
-  }
-  const suffix = parts.length === 0 ? "" : ` (${parts.join(", ")})`;
-  return `${mark} ${assertion.name}${soft ? " [soft]" : ""}${suffix}`;
-}
-
-/**
- * `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 rejectV2ForLegacyCommand({
-        client: auth.client,
-        teamId: auth.teamId,
-        slug,
-      });
-      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: () => {},
-            skipLegacyArchitectureCheck: true,
-          });
-          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 listed = await listSessionsWithSource({
-      baseUrl: target.agentUrl,
-      auth: {
-        bearerToken: options.bearerToken,
-        headers: target.headers,
-      },
-      fetchImpl: options.fetchImpl,
-    });
-    if (options.json === true) {
-      const payload =
-        listed.source === undefined
-          ? { sessions: listed.sessions }
-          : { sessions: listed.sessions, source: listed.source };
-      process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
-      return 0;
-    }
-    process.stdout.write(formatSessionsTable(listed.sessions, { source: listed.source }));
-    return 0;
-  } catch (error) {
-    process.stderr.write(
-      `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n`,
-    );
-    return 1;
-  }
-}
-
-export const HOSTED_RUNS_LAG_NOTE = "Turn running; runs may lag behind events.";
-
-function formatHostedSessionRuns(
-  sessionId: string,
-  runs: AgentkitSessionRuns,
-  events?: AgentkitSessionEventPoll,
-): string {
-  const lines = [`Session ${sessionId}`, `Hosted executions: ${runs.executions.length}`];
-  for (const run of runs.executions) {
-    const failure = run.error?.message ?? run.message ?? "";
-    lines.push(
-      "",
-      `${run.executionId}  ${run.turnStatus}  ${run.durationMs}ms  ${run.writtenAt}  ${failure}`.trimEnd(),
-      ...run.logs.map(log => `  ${log.line}`),
-    );
-  }
-  const latestType = events?.events.at(-1)?.type;
-  if (events !== undefined && events.events.length > 0) {
-    const latest = latestType === undefined ? "" : ` (latest ${latestType})`;
-    lines.push("", `Events: ${events.events.length}${latest}`);
-  }
-  const turnRunning =
-    runs.executions.at(-1)?.turnStatus === "running" ||
-    (runs.executions.length === 0 && events?.execution?.turnStatus === "running");
-  if (turnRunning && (events?.events.length ?? 0) > 0) {
-    lines.push(HOSTED_RUNS_LAG_NOTE);
-  }
-  return `${lines.join("\n")}\n`;
-}
-
-/** Read the v2 runs surface; only its 404 falls through to the v1 engine. */
-async function readHostedSessionRuns(
-  sessionId: string,
-  options: AxCliOptions,
-): Promise<number | "v1"> {
-  const auth = await resolveDeployAuth({
-    team: options.team,
-    apiKey: options.apiKey,
-    fetchImpl: options.fetchImpl,
-  });
-  if (typeof auth === "number") {
-    return auth;
-  }
-  try {
-    const slug = resolveProdSlug(options);
-    const runs = await auth.client.getAgentkitSessionRuns({
-      teamId: auth.teamId,
-      slug,
-      sessionId,
-    });
-    if (options.rawEvents === true || trimNonEmpty(options.out) !== undefined) {
-      process.stderr.write("--events and --out need an engine trajectory.\n");
-      return 2;
-    }
-    const latest = runs.executions.at(-1);
-    const events =
-      runs.executions.length === 0 || latest?.turnStatus === "running"
-        ? await auth.client
-            .getAgentkitSessionEvents({
-              teamId: auth.teamId,
-              slug,
-              sessionId,
-              afterEventIndex: -1,
-            })
-            .catch(() => undefined)
-        : undefined;
-    process.stdout.write(
-      options.json === true
-        ? `${JSON.stringify({ sessionId, ...runs }, null, 2)}\n`
-        : formatHostedSessionRuns(sessionId, runs, events),
-    );
-    return 0;
-  } catch (error) {
-    if (error instanceof DeployApiError && error.status === 404) {
-      return "v1";
-    }
-    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.
- * `--out <path>` → write the raw NDJSON trace to a file instead of printing
- * (same format as `run --events` and the playground download).
- * Interactive reattach: `resume [id]` / `chat --resume` (or `chat --session`).
- */
-export async function cmdSession(
-  sessionId: string | undefined,
-  options: AxCliOptions,
-): Promise<number> {
-  if (options.prod === true && (options.messages?.length ?? 0) > 0) {
-    // `session --prod [ses_…] --message` is the same hosted start as
-    // `run --prod`, with the positional id as the session to resume. Unlike
-    // `run`, a 404 is an error here: this form is explicitly v2.
-    const started = await cmdHostedSession({
-      ...options,
-      sessionId: trimNonEmpty(sessionId) ?? options.sessionId,
-    });
-    if (started === "fallback") {
-      process.stderr.write(
-        `Hosted session start returned 404 for slug ${resolveProdSlug(options)}: deploy a running AgentSDK v2 agent, or use \`${CLI_COMMAND_NAME} run --prod\` (falls back to the v1 engine).\n`,
-      );
-      return 1;
-    }
-    return started;
-  }
-  if (sessionId === undefined || sessionId.trim() === "") {
-    process.stderr.write(
-      `Usage: ${CLI_COMMAND_NAME} session <ses_> [--url | --prod] [--slug <slug>] [--json | --text | --events] [--out <file.ndjson>]\n` +
-        `   or: ${CLI_COMMAND_NAME} session --prod [<sessionId>] --slug <slug> --message "…" [--dry-run] [--as-of <instant>]\n`,
-    );
-    return 2;
-  }
-  if (options.rawEvents === true && options.json === true) {
-    process.stderr.write("--events and --json are mutually exclusive\n");
-    return 2;
-  }
-
-  if (options.prod === true && options.url === undefined) {
-    const hosted = await readHostedSessionRuns(sessionId, options);
-    if (hosted !== "v1") {
-      return hosted;
-    }
-  }
-
-  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,
-    });
-
-    const outPath = trimNonEmpty(options.out);
-    if (outPath !== undefined) {
-      const targetPath = resolve(outPath);
-      await mkdir(dirname(targetPath), { recursive: true });
-      await writeFile(targetPath, `${events.map(e => JSON.stringify(e)).join("\n")}\n`, "utf8");
-      process.stdout.write(`trace: ${targetPath} (${events.length} events)\n`);
-      return 0;
-    }
-
-    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;
-  }
-}
-
-/** Sessions fetched concurrently when `cost` aggregates every session. */
-const COST_FETCH_CONCURRENCY = 4;
-
-/**
- * `cost [sessionId]` — pull per-session cost metrics.
- *
- * With a session id: per-turn token usage + estimated cost for that session.
- * Without one: one row per session (all sessions on the target) plus a
- * total row. `--json` prints the underlying report(s); text is the default.
- * Costs are recorded on `turn.completed` via `POST /v1/models/estimate-cost`
- * (billed usage when available). Turns persisted before cost tracking simply
- * count as unpriced.
- */
-export async function cmdCost(
-  sessionId: string | undefined,
-  options: AxCliOptions,
-): Promise<number> {
-  const target = await resolveSessionTarget(options);
-  if (typeof target === "number") {
-    return target;
-  }
-  const auth = {
-    bearerToken: options.bearerToken,
-    headers: target.headers,
-  };
-
-  try {
-    const resolved = trimNonEmpty(sessionId);
-    if (resolved !== undefined) {
-      const events = await fetchSessionEvents({
-        baseUrl: target.agentUrl,
-        sessionId: resolved,
-        auth,
-        fetchImpl: options.fetchImpl,
-      });
-      const report = buildSessionCostReport(events);
-      if (report.sessionId === "") {
-        report.sessionId = resolved;
-      }
-      if (options.json === true) {
-        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-      } else {
-        process.stdout.write(formatSessionCostText(report));
-      }
-      return 0;
-    }
-
-    const listed = await listSessionsWithSource({
-      baseUrl: target.agentUrl,
-      auth,
-      fetchImpl: options.fetchImpl,
-    });
-    const rows = await mapPool(
-      listed.sessions,
-      COST_FETCH_CONCURRENCY,
-      async (session): Promise<SessionCostRow> => {
-        const events = await fetchSessionEvents({
-          baseUrl: target.agentUrl,
-          sessionId: session.sessionId,
-          auth,
-          fetchImpl: options.fetchImpl,
-        });
-        const report = buildSessionCostReport(events);
-        return {
-          sessionId: session.sessionId,
-          channelId: session.channelId,
-          title: session.title,
-          updatedAt: session.updatedAt,
-          totals: report.totals,
-        };
-      },
-    );
-    if (options.json === true) {
-      process.stdout.write(`${JSON.stringify({ sessions: rows }, null, 2)}\n`);
-    } else {
-      process.stdout.write(formatSessionsCostText(rows));
-    }
-    return 0;
-  } catch (error) {
-    process.stderr.write(
-      `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n`,
-    );
-    return 1;
-  }
-}
-
-/**
- * `playground` — open the local web UI, v1 hosted alias, or v2 portal UI.
- *
- * `--prod` opens the stable v1 alias or the v2 portal URL. `--bearer-token`
- * (and other injected headers) on local targets still run a loopback reverse
- * proxy — Ctrl-C stops that 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 v1 opens the alias playground; v2 opens the portal-hosted shell.
-  if (options.prod === true) {
-    let resolved: Awaited<ReturnType<typeof resolveProdPlaygroundUrl>>;
-    try {
-      resolved = await resolveProdPlaygroundUrl({
-        dir: options.dir,
-        cwd: options.cwd,
-        slug: options.slug,
-        team: options.team,
-        apiKey: options.apiKey,
-        fetchImpl: options.fetchImpl,
-        sessionId,
-      });
-    } catch (error) {
-      process.stderr.write(
-        `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n`,
-      );
-      return 1;
-    }
-
-    process.stdout.write(`${resolved.playgroundUrl}\n`);
-    if (options.print !== true) {
-      openBrowser(resolved.playgroundUrl);
-    }
-    return 0;
-  }
-
-  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(() => {});
-  }
-}