@cursor/bdk 0.2.1

package/src/internal/cli-ax.ts

@@ -0,0 +1,2273 @@
+/**
+ * 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 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 } 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));
+    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)}`);
+    }
+  }
+
+  const target = await resolveTarget(options);
+  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;
+  }
+}
+
+function formatHostedSessionRuns(sessionId: string, runs: AgentkitSessionRuns): 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}`),
+    );
+  }
+  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 runs = await auth.client.getAgentkitSessionRuns({
+      teamId: auth.teamId,
+      slug: resolveProdSlug(options),
+      sessionId,
+    });
+    if (options.rawEvents === true || trimNonEmpty(options.out) !== undefined) {
+      process.stderr.write("--events and --out need an engine trajectory.\n");
+      return 2;
+    }
+    process.stdout.write(
+      options.json === true
+        ? `${JSON.stringify({ sessionId, ...runs }, null, 2)}\n`
+        : formatHostedSessionRuns(sessionId, runs),
+    );
+    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 <sessionId> [--url | --prod] [--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(() => {});
+  }
+}