@cursor/bdk 0.2.1

package/dist/internal/cli-ax.js

@@ -0,0 +1,1864 @@
+/**
+ * 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).
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+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 { serve } from "../index.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 { DeployApiError } from "./deploy-client.js";
+import { CLI_COMMAND_NAME, PACKAGE_NAME } from "./distribution.js";
+import { discoverEvals, filterDiscoveredEvals, runDiscoveredEvals, } from "./eval-runner.js";
+import { cancelRemoteEvalRun, getRemoteEvalRun, listRemoteEvalRuns, listRemoteEvals, pollRemoteEvalRun, RemoteEvalError, snapshotToEvalRunResults, startRemoteEvalRun, } from "./evals-client.js";
+import { runTemplateInit } 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, } 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";
+function shouldStreamProgress(options) {
+    if (options.stream === false) {
+        return false;
+    }
+    if (options.stream === true) {
+        return true;
+    }
+    return process.stderr.isTTY === true;
+}
+function die(message) {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+}
+function pickAgentUrl(handle, slug) {
+    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 !== null && root !== void 0 ? root : handle.agents[0]).url;
+}
+function startEphemeral(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const dir = resolve((_a = options.cwd) !== null && _a !== void 0 ? _a : process.cwd(), options.dir);
+        const stateRoot = (_b = options.stateRoot) !== null && _b !== void 0 ? _b : (yield mkdtemp(join(tmpdir(), "agent-serve-ax-")));
+        const handle = yield serve(dir, Object.assign({ 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) => {
+                process.stderr.write(`${line}\n`);
+            } }, (options.bearerToken === undefined ? {} : { authToken: options.bearerToken })));
+        return {
+            agentUrl: pickAgentUrl(handle, options.slug),
+            close: () => __awaiter(this, void 0, void 0, function* () {
+                // engine.close() can hang on open SDK streams; don't block the CLI.
+                yield Promise.race([
+                    handle.close(),
+                    new Promise(resolve => setTimeout(resolve, 2000)),
+                ]);
+            }),
+        };
+    });
+}
+export function resolveTarget(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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 = yield 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 function cmdInit(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const target = options.initTarget;
+        if (target === undefined || target === "") {
+            printInitGuide();
+            return 0;
+        }
+        let templateDir;
+        let overlayDir;
+        let templateName;
+        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 = (_a = options.cwd) !== null && _a !== void 0 ? _a : 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;
+        let initSpec;
+        if (templateDir !== undefined) {
+            const interview = yield 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 = yield initProject({
+            dir,
+            templateDir,
+            overlayDir,
+            templateName,
+            answers,
+            initSpec,
+        });
+        let signedIn = (yield resolveApiKey()) !== undefined;
+        // Machine-readable path: install deps (piped), never block on browser login.
+        if (options.json) {
+            const install = yield installScaffoldDependencies(result.rootDir, {
+                stdio: "pipe",
+            });
+            const linked = install.ok
+                ? yield linkCliOntoPath(result.rootDir, { stdio: "pipe" })
+                : undefined;
+            const cliOnPath = (linked === null || linked === void 0 ? void 0 : linked.ok) === true;
+            process.stdout.write(`${JSON.stringify({
+                ok: install.ok,
+                directory: result.rootDir,
+                template: (_b = options.template) !== null && _b !== void 0 ? _b : 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 = yield 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 = yield 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 {
+            yield 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 = yield ensureCursorLogin({ interactive: true });
+            signedIn = loginExit === 0 && (yield 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 function cmdResume(sessionId, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const resolved = (_a = trimNonEmpty(sessionId)) !== null && _a !== void 0 ? _a : trimNonEmpty(options.sessionId);
+        if (resolved !== undefined) {
+            return cmdChat(Object.assign(Object.assign({}, options), { sessionId: resolved, resume: false }));
+        }
+        return cmdChat(Object.assign(Object.assign({}, options), { sessionId: undefined, resume: true }));
+    });
+}
+function trimNonEmpty(value) {
+    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 function cmdChat(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b, _c;
+        const message = (_a = options.messages) === null || _a === void 0 ? void 0 : _a[0];
+        // chat never starts an ephemeral server — default to local serve URL.
+        const target = yield resolveTarget(Object.assign(Object.assign({}, options), { url: options.prod === true ? undefined : ((_b = options.url) !== null && _b !== void 0 ? _b : "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 = yield 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 = yield 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 = yield 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: (_c = result.continuationToken) !== null && _c !== void 0 ? _c : null,
+                    trajectory: result.trajectory,
+                }, null, 2));
+            }
+            return result.ok ? 0 : 1;
+        }
+        try {
+            yield 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 function cmdRun(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        // 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 = yield cmdHostedSession(options);
+            if (started !== "fallback") {
+                return started;
+            }
+        }
+        const messages = (_a = options.messages) !== null && _a !== void 0 ? _a : [];
+        if (messages.length === 0) {
+            die("Provide --message (repeatable) or --messages-file");
+        }
+        const stream = shouldStreamProgress(options);
+        const progress = stream ? createStreamProgress() : undefined;
+        const target = yield resolveTarget(options);
+        try {
+            if (stream) {
+                process.stderr.write(`→ ${target.agentUrl}\n`);
+            }
+            const result = yield 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;
+            const writeEvents = options.events !== false;
+            if (writeEvents) {
+                if (typeof options.events === "string") {
+                    eventsPath = resolve(options.events);
+                }
+                else {
+                    const root = resolve((_b = options.cwd) !== null && _b !== void 0 ? _b : process.cwd(), options.dir);
+                    const tracesDir = join(root, ".agent-serve", "traces");
+                    yield mkdir(tracesDir, { recursive: true });
+                    eventsPath = join(tracesDir, `${result.sessionId}.ndjson`);
+                }
+                yield 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: (_c = result.continuationToken) !== null && _c !== void 0 ? _c : null,
+                    trace: eventsPath !== null && eventsPath !== void 0 ? 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 === null || progress === void 0 ? void 0 : progress.close();
+            if (target.close !== undefined) {
+                yield 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) {
+    var _a;
+    var _b;
+    if (options.url !== undefined) {
+        return "--prod session start talks to the agentsdk control plane; do not pass --url";
+    }
+    const messages = (_b = options.messages) !== null && _b !== void 0 ? _b : [];
+    if (messages.length !== 1 || ((_a = messages[0]) === null || _a === void 0 ? void 0 : _a.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;
+}
+function cmdHostedSession(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const rejection = hostedSessionRejection(options);
+        if (rejection !== undefined) {
+            die(rejection);
+        }
+        const messages = (_a = options.messages) !== null && _a !== void 0 ? _a : [];
+        const sessionId = trimNonEmpty(options.sessionId);
+        const auth = yield resolveDeployAuth({
+            team: options.team,
+            apiKey: options.apiKey,
+            fetchImpl: options.fetchImpl,
+        });
+        if (typeof auth === "number") {
+            return auth;
+        }
+        const slug = resolveProdSlug(options);
+        try {
+            const accepted = yield 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.
+ */
+function fetchAgentJson(target_1, path_1) {
+    return __awaiter(this, arguments, void 0, function* (target, path, args = {}) {
+        const headers = {};
+        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 = yield fetch(`${target.agentUrl}${path}`, {
+            method: args.method,
+            headers,
+            body: args.body,
+        });
+        const payload = yield response.json().catch(() => undefined);
+        return { response, payload };
+    });
+}
+function printInvalidResponse() {
+    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 function cmdCall(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const toolName = options.toolName;
+        if (toolName === undefined || toolName === "") {
+            die(`Provide a tool name: ${CLI_COMMAND_NAME} call <tool> [--input '{...}']`);
+        }
+        let input = {};
+        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 = yield resolveTarget(options);
+        try {
+            const body = { input };
+            if (options.sessionId !== undefined) {
+                body.sessionId = options.sessionId;
+            }
+            const { response, payload } = yield 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.ok === true;
+            return ok ? 0 : 1;
+        }
+        finally {
+            if (target.close !== undefined) {
+                yield 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 function cmdSkill(skillName, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (skillName === undefined || skillName === "") {
+            process.stderr.write(`Usage: ${CLI_COMMAND_NAME} skill <name> [--dir <path> | --url <baseUrl> | --prod]\n`);
+            return 2;
+        }
+        const target = yield resolveTarget(options);
+        try {
+            const { response, payload } = yield fetchAgentJson(target, `/v1/skills/${encodeURIComponent(skillName)}`, { bearerToken: options.bearerToken });
+            if (payload === undefined) {
+                printInvalidResponse();
+                return 1;
+            }
+            if (options.text === true && response.ok) {
+                const skillMd = payload.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) {
+                yield target.close();
+            }
+        }
+    });
+}
+export function cmdTrajectory(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (typeof options.events !== "string") {
+            die(`trajectory requires --events <file.ndjson> (write one with: ${CLI_COMMAND_NAME} run --events …)`);
+        }
+        const trajectory = yield 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) {
+    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. */
+function resolveEvalTarget(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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 = yield 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 function cmdEval(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b;
+        const projectRoot = resolve((_b = options.cwd) !== null && _b !== void 0 ? _b : 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 = yield resolveEvalTarget(options);
+            if (typeof target === "number") {
+                return target;
+            }
+            try {
+                const listed = yield listRemoteEvals({
+                    baseUrl: target.agentUrl,
+                    auth: {
+                        bearerToken: options.bearerToken,
+                        headers: target.headers,
+                    },
+                    fetchImpl: options.fetchImpl,
+                    filterIds,
+                    tags,
+                });
+                return printListedEvals(listed.map(e => { var _a; return ({
+                    id: e.id,
+                    fileId: e.fileId,
+                    description: e.description,
+                    tags: (_a = e.tags) !== null && _a !== void 0 ? _a : [],
+                }); }), 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) {
+                    yield target.close();
+                }
+            }
+        }
+        const target = yield 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 = yield 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 yield printEvalResults(results, options, undefined, artifactsDir);
+                }
+                finally {
+                    progress === null || progress === void 0 ? void 0 : progress.close();
+                }
+            }
+            try {
+                if (options.noWait === true) {
+                    const started = yield startRemoteEvalRun({
+                        baseUrl: target.agentUrl,
+                        filterIds,
+                        tags,
+                        timeoutMs: options.timeoutMs,
+                        verbose: Boolean(options.verbose),
+                        auth: {
+                            bearerToken: options.bearerToken,
+                            headers: target.headers,
+                        },
+                        fetchImpl: options.fetchImpl,
+                    });
+                    return yield 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 = yield startRemoteEvalRun({
+                    baseUrl: target.agentUrl,
+                    filterIds,
+                    tags,
+                    timeoutMs: options.timeoutMs,
+                    verbose: Boolean(options.verbose) || stream,
+                    auth: {
+                        bearerToken: options.bearerToken,
+                        headers: target.headers,
+                    },
+                    fetchImpl: options.fetchImpl,
+                });
+                yield printEvalIdBanner(started, options, target.agentUrl);
+                (_a = progress === null || progress === void 0 ? void 0 : progress.onSnapshot) === null || _a === void 0 ? void 0 : _a.call(progress, started);
+                const snapshot = yield 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 yield 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) {
+                yield target.close();
+            }
+        }
+    });
+}
+/**
+ * Flags to re-target the same surface from an `eval --no-wait` hint.
+ * Exported for tests.
+ */
+export function formatEvalStatusFlags(options) {
+    const parts = [];
+    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. */
+function printEvalIdBanner(started, options, agentUrl) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const pollPath = `${agentUrl.replace(/\/$/, "")}/v1/dev/evals/runs/${started.runId}`;
+        const statusFlags = formatEvalStatusFlags(options);
+        const playgroundUrl = yield 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(Object.assign({ 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. */
+function printEvalAccepted(started, options, agentUrl) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const pollPath = `${agentUrl.replace(/\/$/, "")}/v1/dev/evals/runs/${started.runId}`;
+        const statusFlags = formatEvalStatusFlags(options);
+        const playgroundUrl = yield resolveEvalPlaygroundDeepLink(options, started.runId, agentUrl);
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(Object.assign({ 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).
+ */
+function resolveEvalPlaygroundDeepLink(options, runId, agentUrl) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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 (_a) {
+                return undefined;
+            }
+        }
+        try {
+            const resolved = yield 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 (_b) {
+            return undefined;
+        }
+    });
+}
+/**
+ * `eval cancel <runId>` — cancel a running remote batch by Eval ID.
+ */
+export function cmdEvalCancel(runId, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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 = yield resolveEvalTarget(options);
+        if (typeof target === "number") {
+            return target;
+        }
+        try {
+            const snap = yield 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) {
+                yield 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 function cmdEvalStatus(runId, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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 = yield resolveEvalTarget(options);
+        if (typeof target === "number") {
+            return target;
+        }
+        const auth = {
+            bearerToken: options.bearerToken,
+            headers: target.headers,
+        };
+        try {
+            if (runId === undefined || runId === "") {
+                const { runs, activeRunId } = yield 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 = yield getRemoteEvalRun({
+                baseUrl: target.agentUrl,
+                runId,
+                auth,
+                fetchImpl: options.fetchImpl,
+            });
+            const outPath = yield 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) {
+                yield target.close();
+            }
+        }
+    });
+}
+function formatEvalRunSummaryLine(run) {
+    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}`;
+}
+function listLocalEvals(projectRoot, options, filterIds, tags) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { evals } = yield discoverEvals(projectRoot);
+        const listed = filterDiscoveredEvals(evals, { filterIds, tags });
+        return printListedEvals(listed.map(e => { var _a; return ({
+            id: e.id,
+            fileId: e.fileId,
+            path: e.path,
+            description: e.definition.description,
+            tags: (_a = e.definition.tags) !== null && _a !== void 0 ? _a : [],
+        }); }), options, `No evals under ${projectRoot}/evals`);
+    });
+}
+function printListedEvals(listed, options, emptyMessage) {
+    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) {
+    if (!enabled) {
+        return undefined;
+    }
+    let lastSummaryKey = "";
+    const seenCaseKeys = new Set();
+    return {
+        onSnapshot(snap) {
+            var _a, _b;
+            // 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"}:${(_a = c.durationMs) !== null && _a !== void 0 ? _a : 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 (_b = c.logs) !== null && _b !== void 0 ? _b : []) {
+                    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, options) {
+    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, artifactsDir) {
+    const reporters = [];
+    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) {
+    var _a;
+    return (_a = result.verdict) !== null && _a !== void 0 ? _a : (result.ok ? "passed" : "failed");
+}
+const EVAL_VERDICT_LABEL = {
+    passed: "PASS",
+    failed: "FAIL",
+    scored: "SCORED",
+    skipped: "SKIP",
+};
+function printEvalResults(results, options, batch, artifactsDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        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 === null || batch === void 0 ? void 0 : batch.status) === "failed";
+        const ok = counts.failed === 0 && !(strict && counts.scored > 0) && !batchFailed;
+        if ((batch === null || batch === void 0 ? void 0 : 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 = Object.assign(Object.assign(Object.assign(Object.assign({ ok, passed: counts.passed, failed: counts.failed, scored: counts.scored, skipped: counts.skipped, strict,
+            results }, (artifactsDir === undefined ? {} : { artifactsDir })), ((batch === null || batch === void 0 ? void 0 : batch.runId) === undefined ? {} : { runId: batch.runId })), ((batch === null || batch === void 0 ? void 0 : batch.status) === undefined ? {} : { status: batch.status })), ((batch === null || batch === void 0 ? void 0 : batch.error) === undefined || batch.error === "" ? {} : { error: batch.error }));
+        const outPath = yield 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((_a = r.metrics) !== null && _a !== void 0 ? _a : {})) {
+                    process.stdout.write(`  metric ${name}=${String(value)}\n`);
+                }
+                for (const line of (_b = r.logs) !== null && _b !== void 0 ? _b : []) {
+                    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 = [];
+            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.
+ */
+function writeJsonOutFile(out, payload) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const trimmed = trimNonEmpty(out);
+        if (trimmed === undefined) {
+            return undefined;
+        }
+        const target = resolve(trimmed);
+        yield mkdir(dirname(target), { recursive: true });
+        yield 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) {
+    var _a;
+    const soft = ((_a = assertion.severity) !== null && _a !== void 0 ? _a : "gate") === "soft";
+    const mark = assertion.passed ? "✓" : soft ? "~" : "✗";
+    const parts = [];
+    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 function cmdLogs(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        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 = () => {
+            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 = yield resolveDeployAuth({
+                    team: options.team,
+                    apiKey: options.apiKey,
+                    fetchImpl: options.fetchImpl,
+                });
+                if (typeof auth === "number") {
+                    return auth;
+                }
+                yield rejectV2ForLegacyCommand({
+                    client: auth.client,
+                    teamId: auth.teamId,
+                    slug,
+                });
+                yield 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: () => __awaiter(this, void 0, void 0, function* () {
+                        const target = yield 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;
+            }
+            yield runLogsTail({
+                dir: options.dir,
+                cwd: options.cwd,
+                url: (_a = options.url) !== null && _a !== void 0 ? _a : "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. */
+function resolveSessionTarget(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        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 = yield 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: ((_a = options.url) !== null && _a !== void 0 ? _a : "http://127.0.0.1:3000").replace(/\/$/, ""),
+        };
+    });
+}
+/**
+ * `sessions` — list sessions on a running (or `--prod` hosted) agent.
+ */
+export function cmdSessions(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const target = yield resolveSessionTarget(options);
+        if (typeof target === "number") {
+            return target;
+        }
+        try {
+            const listed = yield 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, runs) {
+    var _a;
+    var _b, _c;
+    const lines = [`Session ${sessionId}`, `Hosted executions: ${runs.executions.length}`];
+    for (const run of runs.executions) {
+        const failure = (_c = (_b = (_a = run.error) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : run.message) !== null && _c !== void 0 ? _c : "";
+        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. */
+function readHostedSessionRuns(sessionId, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const auth = yield resolveDeployAuth({
+            team: options.team,
+            apiKey: options.apiKey,
+            fetchImpl: options.fetchImpl,
+        });
+        if (typeof auth === "number") {
+            return auth;
+        }
+        try {
+            const runs = yield 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(Object.assign({ 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 function cmdSession(sessionId, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b, _c;
+        if (options.prod === true && ((_b = (_a = options.messages) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 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 = yield cmdHostedSession(Object.assign(Object.assign({}, options), { sessionId: (_c = trimNonEmpty(sessionId)) !== null && _c !== void 0 ? _c : 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 = yield readHostedSessionRuns(sessionId, options);
+            if (hosted !== "v1") {
+                return hosted;
+            }
+        }
+        const target = yield resolveSessionTarget(options);
+        if (typeof target === "number") {
+            return target;
+        }
+        try {
+            const events = yield 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);
+                yield mkdir(dirname(targetPath), { recursive: true });
+                yield 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 function cmdCost(sessionId, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const target = yield 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 = yield 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 = yield listSessionsWithSource({
+                baseUrl: target.agentUrl,
+                auth,
+                fetchImpl: options.fetchImpl,
+            });
+            const rows = yield mapPool(listed.sessions, COST_FETCH_CONCURRENCY, (session) => __awaiter(this, void 0, void 0, function* () {
+                const events = yield 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 function cmdPlayground(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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;
+            try {
+                resolved = yield 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 = yield 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;
+        try {
+            proxy = yield 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 yield runPlaygroundProxySession({
+            proxy,
+            sessionId,
+            print: options.print === true,
+            signal: options.signal,
+        });
+    });
+}
+function runPlaygroundProxySession(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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 = () => {
+            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 {
+            yield new Promise(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 === null || external === void 0 ? void 0 : external.removeEventListener("abort", onSignal);
+            yield proxy.close().catch(() => { });
+        }
+    });
+}