@cursor/july 0.1.20 → 0.1.21

package/src/internal/resolve-prod-target.test.ts

@@ -0,0 +1,787 @@
+import { once } from "node:events";
+import { mkdtemp, rm } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  cmdCall,
+  cmdEval,
+  cmdEvalStatus,
+  cmdRun,
+  formatEvalStatusFlags,
+  resolveEvalTargetMode,
+  resolveTarget,
+} from "./cli-ax.js";
+import {
+  PROD_ENGINE_WAKE_HEADERS,
+  ProdTargetError,
+  resolveProdAliasPlaygroundUrl,
+  resolveProdSlug,
+  resolveProdTarget,
+} from "./resolve-prod-target.js";
+
+const API_KEY = "test-api-key";
+const TEAM_ID = 42;
+
+interface MockBackend {
+  url: string;
+  close: () => Promise<void>;
+  setDeployment: (slug: string, body: Record<string, unknown>) => void;
+}
+
+async function startMockBackend(): Promise<MockBackend> {
+  const deployments = new Map<string, Record<string, unknown>>();
+  const server: Server = createServer((req, res) => {
+    let raw = "";
+    req.on("data", (chunk: Buffer) => {
+      raw += chunk.toString("utf8");
+    });
+    req.on("end", () => {
+      void raw;
+      const url = new URL(req.url ?? "/", "http://localhost");
+      const send = (status: number, body: unknown): void => {
+        res.writeHead(status, { "content-type": "application/json" });
+        res.end(JSON.stringify(body));
+      };
+
+      if (url.pathname === "/auth/exchange_user_api_key") {
+        const claims = Buffer.from(
+          JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 3600 })
+        ).toString("base64url");
+        send(200, { accessToken: `header.${claims}.signature` });
+        return;
+      }
+      if (url.pathname === "/aiserver.v1.DashboardService/GetMe") {
+        send(200, {
+          authId: "auth0|1",
+          email: "dev@example.com",
+          teamId: TEAM_ID,
+          teamName: "Acme",
+        });
+        return;
+      }
+
+      const prefix = "/internal/agent-serve/deployments/";
+      if (
+        req.method === "GET" &&
+        url.pathname.startsWith(prefix) &&
+        req.headers.authorization === `Bearer ${API_KEY}`
+      ) {
+        const slug = decodeURIComponent(url.pathname.slice(prefix.length));
+        const detail = deployments.get(slug);
+        if (detail === undefined) {
+          send(404, { error: "Deployment not found" });
+          return;
+        }
+        send(200, detail);
+        return;
+      }
+
+      send(404, { error: "Not found" });
+    });
+  });
+
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const { port } = server.address() as AddressInfo;
+  return {
+    url: `http://127.0.0.1:${port}`,
+    setDeployment: (slug, body) => {
+      deployments.set(slug, body);
+    },
+    close: () =>
+      new Promise<void>((resolvePromise, reject) =>
+        server.close((error) => (error ? reject(error) : resolvePromise()))
+      ),
+  };
+}
+
+interface StubEngine {
+  url: string;
+  close: () => Promise<void>;
+  sessionHeaders: Array<Record<string, string | string[] | undefined>>;
+  toolHeaders: Array<Record<string, string | string[] | undefined>>;
+  evalRunHeaders: Array<Record<string, string | string[] | undefined>>;
+  evalRunBodies: unknown[];
+}
+
+async function startStubEngine(): Promise<StubEngine> {
+  const sessionHeaders: StubEngine["sessionHeaders"] = [];
+  const toolHeaders: StubEngine["toolHeaders"] = [];
+  const evalRunHeaders: StubEngine["evalRunHeaders"] = [];
+  const evalRunBodies: unknown[] = [];
+  const evalSnapshot = {
+    runId: "evalrun_test",
+    status: "completed" as const,
+    startedAt: "2026-07-20T00:00:00.000Z",
+    finishedAt: "2026-07-20T00:00:01.000Z",
+    summary: { passed: 1, failed: 0, total: 1, done: 1 },
+    cases: [
+      {
+        id: "smoke",
+        fileId: "smoke",
+        status: "done" as const,
+        ok: true,
+        assertions: [{ name: "succeeded", passed: true }],
+        durationMs: 10,
+        inputs: [],
+        logs: [],
+      },
+    ],
+    config: { maxConcurrency: 1, durableRuns: true },
+  };
+  const server: Server = createServer((req, res) => {
+    let raw = "";
+    req.on("data", (chunk: Buffer) => {
+      raw += chunk.toString("utf8");
+    });
+    req.on("end", () => {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      const send = (status: number, body: unknown): void => {
+        res.writeHead(status, { "content-type": "application/json" });
+        res.end(JSON.stringify(body));
+      };
+      const sendNdjson = (lines: unknown[]): void => {
+        res.writeHead(200, { "content-type": "application/x-ndjson" });
+        res.end(`${lines.map((line) => JSON.stringify(line)).join("\n")}\n`);
+      };
+
+      if (req.method === "POST" && url.pathname === "/v1/dev/evals/runs") {
+        evalRunHeaders.push({ ...req.headers });
+        evalRunBodies.push(raw === "" ? {} : JSON.parse(raw));
+        send(202, {
+          ...evalSnapshot,
+          status: "running",
+          finishedAt: undefined,
+        });
+        return;
+      }
+      if (req.method === "GET" && url.pathname === "/v1/dev/evals/runs") {
+        send(200, { runs: [evalSnapshot], activeRunId: undefined });
+        return;
+      }
+      if (
+        req.method === "GET" &&
+        url.pathname === "/v1/dev/evals/runs/evalrun_test"
+      ) {
+        send(200, evalSnapshot);
+        return;
+      }
+      if (
+        req.method === "GET" &&
+        url.pathname === "/v1/dev/evals/runs/evalrun_running"
+      ) {
+        send(200, {
+          ...evalSnapshot,
+          runId: "evalrun_running",
+          status: "running",
+          finishedAt: undefined,
+          cases: evalSnapshot.cases.map((c) => ({
+            ...c,
+            status: "running" as const,
+            ok: undefined,
+          })),
+        });
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/v1/session") {
+        sessionHeaders.push({ ...req.headers });
+        send(200, {
+          ok: true,
+          sessionId: "ses_test",
+          continuationToken: "http:tok",
+        });
+        return;
+      }
+      if (
+        req.method === "GET" &&
+        url.pathname === "/v1/session/ses_test/stream"
+      ) {
+        sendNdjson([
+          {
+            index: 0,
+            sessionId: "ses_test",
+            type: "session.started",
+            data: { channelId: "http" },
+          },
+          {
+            index: 1,
+            sessionId: "ses_test",
+            turnId: "turn_1",
+            type: "turn.started",
+            data: {},
+          },
+          {
+            index: 2,
+            sessionId: "ses_test",
+            turnId: "turn_1",
+            type: "message.completed",
+            data: { text: "pong", finishReason: "stop" },
+          },
+          {
+            index: 3,
+            sessionId: "ses_test",
+            turnId: "turn_1",
+            type: "turn.completed",
+            data: { result: "pong" },
+          },
+          {
+            index: 4,
+            sessionId: "ses_test",
+            type: "session.waiting",
+            data: {},
+          },
+        ]);
+        return;
+      }
+      if (req.method === "POST" && url.pathname.startsWith("/v1/tools/")) {
+        toolHeaders.push({ ...req.headers });
+        send(200, { ok: true, output: { echoed: "hi" } });
+        return;
+      }
+      send(404, { ok: false, error: "not_found" });
+    });
+  });
+
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const { port } = server.address() as AddressInfo;
+  return {
+    url: `http://127.0.0.1:${port}`,
+    sessionHeaders,
+    toolHeaders,
+    evalRunHeaders,
+    evalRunBodies,
+    close: () =>
+      new Promise<void>((resolvePromise, reject) =>
+        server.close((error) => (error ? reject(error) : resolvePromise()))
+      ),
+  };
+}
+
+function runningDetail(
+  slug: string,
+  engineUrl: string
+): Record<string, unknown> {
+  return {
+    id: 1,
+    slug,
+    teamId: TEAM_ID,
+    deploymentKind: "repo",
+    status: "running",
+    generation: 1,
+    engineAlias: `/internal/agent-serve/agents/asd_test/engine`,
+    engineAccess: {
+      url: engineUrl,
+      headers: { "x-anyrun-port-token": "port-tok-1" },
+      expiresAt: "2099-01-01T00:00:00.000Z",
+    },
+  };
+}
+
+describe("resolveEvalTargetMode", () => {
+  it("defaults to local; --prod and --url opt into remote surfaces", () => {
+    expect(resolveEvalTargetMode({})).toBe("local");
+    expect(resolveEvalTargetMode({ prod: true })).toBe("deployment");
+    expect(resolveEvalTargetMode({ url: "http://127.0.0.1:3000" })).toBe("url");
+  });
+
+  it("rejects conflicting target flags", () => {
+    expect(resolveEvalTargetMode({ prod: true, url: "http://x" })).toEqual({
+      error: "--prod and --url are mutually exclusive",
+    });
+  });
+});
+
+describe("formatEvalStatusFlags", () => {
+  it("includes --slug/--team for --prod and --url/--team for --url", () => {
+    expect(formatEvalStatusFlags({ prod: true })).toBe(" --prod");
+    expect(
+      formatEvalStatusFlags({ prod: true, slug: "approval-buddy", team: "1" })
+    ).toBe(" --prod --slug approval-buddy --team 1");
+    expect(
+      formatEvalStatusFlags({ url: "http://127.0.0.1:3000/", team: "7" })
+    ).toBe(" --url http://127.0.0.1:3000 --team 7");
+  });
+});
+
+describe("resolveProdSlug", () => {
+  it("uses --slug when provided", () => {
+    expect(resolveProdSlug({ dir: ".", slug: "danny" })).toBe("danny");
+  });
+
+  it("derives from directory basename", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "Danny Agent-"));
+    // basename is like "Danny Agent-xxxxx" → slugFromDirectoryName lowercases
+    const slug = resolveProdSlug({ dir });
+    expect(slug).toMatch(/^danny-agent-/);
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("rejects invalid --slug", () => {
+    expect(() => resolveProdSlug({ dir: ".", slug: "Bad Slug" })).toThrow(
+      /Invalid slug/
+    );
+  });
+});
+
+describe("resolveProdTarget / --prod", () => {
+  let backend: MockBackend;
+  let engine: StubEngine;
+  const savedEnv: Record<string, string | undefined> = {};
+  let agentDir: string;
+
+  beforeEach(async () => {
+    backend = await startMockBackend();
+    engine = await startStubEngine();
+    for (const key of [
+      "CURSOR_API_BASE_URL",
+      "CURSOR_API_KEY",
+      "AGENT_SERVE_CONFIG_DIR",
+    ]) {
+      savedEnv[key] = process.env[key];
+    }
+    process.env.CURSOR_API_BASE_URL = backend.url;
+    delete process.env.CURSOR_API_KEY;
+    process.env.AGENT_SERVE_CONFIG_DIR = join(
+      tmpdir(),
+      `agentkit-prod-test-${process.pid}`
+    );
+    agentDir = await mkdtemp(join(tmpdir(), "danny-"));
+  });
+
+  afterEach(async () => {
+    await backend.close();
+    await engine.close();
+    await rm(agentDir, { recursive: true, force: true });
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  it("resolves slug from dir name and returns engineAccess headers", async () => {
+    const slug = resolveProdSlug({ dir: agentDir });
+    backend.setDeployment(slug, runningDetail(slug, engine.url));
+    const stderr: string[] = [];
+
+    const target = await resolveProdTarget({
+      dir: agentDir,
+      team: String(TEAM_ID),
+      apiKey: API_KEY,
+      err: (text) => stderr.push(text),
+    });
+
+    expect(target.slug).toBe(slug);
+    expect(target.agentUrl).toBe(engine.url);
+    expect(target.headers["x-anyrun-port-token"]).toBe("port-tok-1");
+    expect(target.headers["x-anyrun-hibernation-lower-bound-s"]).toBe(
+      PROD_ENGINE_WAKE_HEADERS["x-anyrun-hibernation-lower-bound-s"]
+    );
+    expect(target.headers["x-anyrun-hibernation-upper-bound-s"]).toBe(
+      PROD_ENGINE_WAKE_HEADERS["x-anyrun-hibernation-upper-bound-s"]
+    );
+    expect(stderr.join("")).toContain(`Using hosted deployment "${slug}".`);
+    expect(stderr.join("")).not.toMatch(/engine access|expires/i);
+  });
+
+  it("honors --slug override", async () => {
+    backend.setDeployment("weather", runningDetail("weather", engine.url));
+    const target = await resolveProdTarget({
+      dir: agentDir,
+      slug: "weather",
+      team: String(TEAM_ID),
+      apiKey: API_KEY,
+      err: () => {},
+    });
+    expect(target.slug).toBe("weather");
+  });
+
+  it("fails when deployment is not running", async () => {
+    backend.setDeployment("danny", {
+      ...runningDetail("danny", engine.url),
+      status: "stopped",
+      engineAccess: null,
+    });
+    await expect(
+      resolveProdTarget({
+        dir: agentDir,
+        slug: "danny",
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+        err: () => {},
+      })
+    ).rejects.toThrow(/stopped, not running/);
+  });
+
+  it("fails when engineAccess is missing", async () => {
+    backend.setDeployment("danny", {
+      ...runningDetail("danny", engine.url),
+      engineAccess: null,
+    });
+    await expect(
+      resolveProdTarget({
+        dir: agentDir,
+        slug: "danny",
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+        err: () => {},
+        sleep: async () => {},
+      })
+    ).rejects.toThrow(/is not reachable yet/);
+  });
+
+  it("retries when engineAccess appears after a wake", async () => {
+    backend.setDeployment("danny", {
+      ...runningDetail("danny", engine.url),
+      engineAccess: null,
+    });
+    const stderr: string[] = [];
+    const sleepCalls: number[] = [];
+    const target = await resolveProdTarget({
+      dir: agentDir,
+      slug: "danny",
+      team: String(TEAM_ID),
+      apiKey: API_KEY,
+      err: (text) => stderr.push(text),
+      sleep: async (ms) => {
+        sleepCalls.push(ms);
+        // After the first miss, the engine becomes reachable (wake).
+        backend.setDeployment("danny", runningDetail("danny", engine.url));
+      },
+    });
+    expect(target.agentUrl).toBe(engine.url);
+    expect(sleepCalls).toEqual([1000]);
+    expect(stderr.join("")).toContain("is waking");
+  });
+
+  it("rejects --prod with --url", async () => {
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit");
+    }) as never);
+    const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+    try {
+      await expect(
+        resolveTarget({
+          dir: agentDir,
+          prod: true,
+          url: "http://127.0.0.1:3000",
+        })
+      ).rejects.toThrow(/process\.exit/);
+      expect(
+        errSpy.mock.calls.some((c) =>
+          String(c[0]).includes("mutually exclusive")
+        )
+      ).toBe(true);
+    } finally {
+      exitSpy.mockRestore();
+      errSpy.mockRestore();
+    }
+  });
+
+  it("cmdRun --prod sends X-Anyrun-Port-Token on /v1/session", async () => {
+    const slug = resolveProdSlug({ dir: agentDir });
+    backend.setDeployment(slug, runningDetail(slug, engine.url));
+
+    const code = await cmdRun({
+      dir: agentDir,
+      prod: true,
+      team: String(TEAM_ID),
+      apiKey: API_KEY,
+      messages: ["hello"],
+      events: false,
+      stream: false,
+    });
+
+    expect(code).toBe(0);
+    expect(engine.sessionHeaders.length).toBe(1);
+    expect(engine.sessionHeaders[0]!["x-anyrun-port-token"]).toBe("port-tok-1");
+    expect(
+      engine.sessionHeaders[0]!["x-anyrun-hibernation-lower-bound-s"]
+    ).toBe("1800");
+  });
+
+  it("marks a missing deployment as notFound", async () => {
+    const error = await resolveProdTarget({
+      dir: agentDir,
+      slug: "danny",
+      team: String(TEAM_ID),
+      apiKey: API_KEY,
+      err: () => {},
+    }).then(
+      () => undefined,
+      (thrown: unknown) => thrown
+    );
+    expect(error).toBeInstanceOf(ProdTargetError);
+    expect((error as ProdTargetError).notFound).toBe(true);
+    expect((error as ProdTargetError).slug).toBe("danny");
+  });
+
+  it("cmdEval --prod explains when the deployment is missing", async () => {
+    const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+    try {
+      const code = await cmdEval({
+        dir: agentDir,
+        prod: true,
+        slug: "danny",
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+        stream: false,
+      });
+      expect(code).toBe(1);
+      const stderr = errSpy.mock.calls.map((c) => String(c[0])).join("");
+      // The API 404 text is kept (it distinguishes a missing deployment
+      // from a wrong host / disabled gate), plus the deploy/local hints.
+      expect(stderr).toContain('Deployment "danny"');
+      expect(stderr).toContain("not found");
+      expect(stderr).toContain("deploy --slug danny");
+      expect(stderr).toContain("omit --prod");
+    } finally {
+      errSpy.mockRestore();
+    }
+  });
+
+  it("cmdEval --prod starts a server-side persisted eval batch", async () => {
+    const slug = resolveProdSlug({ dir: agentDir });
+    backend.setDeployment(slug, runningDetail(slug, engine.url));
+    const outSpy = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+    try {
+      const code = await cmdEval({
+        dir: agentDir,
+        prod: true,
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+        stream: false,
+        evalIds: ["smoke"],
+      });
+      expect(code).toBe(0);
+      expect(engine.evalRunHeaders.length).toBe(1);
+      expect(engine.evalRunHeaders[0]!["x-anyrun-port-token"]).toBe(
+        "port-tok-1"
+      );
+      expect(engine.evalRunBodies[0]).toEqual({ filterIds: ["smoke"] });
+      // Must not fall back to the client-side session harness.
+      expect(engine.sessionHeaders.length).toBe(0);
+      const stdout = outSpy.mock.calls.map((c) => String(c[0])).join("");
+      expect(stdout).toContain("PASS  smoke");
+    } finally {
+      outSpy.mockRestore();
+      errSpy.mockRestore();
+    }
+  });
+
+  it("cmdEval --prod --no-wait accepts the batch without polling", async () => {
+    const slug = resolveProdSlug({ dir: agentDir });
+    backend.setDeployment(slug, runningDetail(slug, engine.url));
+    const outSpy = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+    try {
+      const code = await cmdEval({
+        dir: agentDir,
+        prod: true,
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+        stream: false,
+        noWait: true,
+        evalIds: ["smoke"],
+      });
+      expect(code).toBe(0);
+      expect(engine.evalRunHeaders.length).toBe(1);
+      expect(engine.evalRunBodies[0]).toEqual({ filterIds: ["smoke"] });
+      const stdout = outSpy.mock.calls.map((c) => String(c[0])).join("");
+      expect(stdout).toContain("Eval ID: evalrun_test");
+      expect(stdout).toContain(
+        `eval status evalrun_test --prod --team ${TEAM_ID}`
+      );
+      expect(stdout).toContain("/v1/dev/evals/runs/evalrun_test");
+    } finally {
+      outSpy.mockRestore();
+      errSpy.mockRestore();
+    }
+  });
+
+  it("cmdEvalStatus --prod fetches a run and lists recent runs", async () => {
+    const slug = resolveProdSlug({ dir: agentDir });
+    backend.setDeployment(slug, runningDetail(slug, engine.url));
+    const outSpy = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+    try {
+      const one = await cmdEvalStatus("evalrun_test", {
+        dir: agentDir,
+        prod: true,
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+      });
+      expect(one).toBe(0);
+      let stdout = outSpy.mock.calls.map((c) => String(c[0])).join("");
+      expect(stdout).toContain("evalrun_test  completed");
+      expect(stdout).toContain("PASS  smoke");
+
+      outSpy.mockClear();
+      const listed = await cmdEvalStatus(undefined, {
+        dir: agentDir,
+        prod: true,
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+      });
+      expect(listed).toBe(0);
+      stdout = outSpy.mock.calls.map((c) => String(c[0])).join("");
+      expect(stdout).toContain("evalrun_test  completed");
+    } finally {
+      outSpy.mockRestore();
+      errSpy.mockRestore();
+    }
+  });
+
+  it("cmdEvalStatus exits 3 while the remote batch is still running", async () => {
+    const slug = resolveProdSlug({ dir: agentDir });
+    backend.setDeployment(slug, runningDetail(slug, engine.url));
+    const outSpy = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+    try {
+      const code = await cmdEvalStatus("evalrun_running", {
+        dir: agentDir,
+        prod: true,
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+      });
+      expect(code).toBe(3);
+      const stdout = outSpy.mock.calls.map((c) => String(c[0])).join("");
+      expect(stdout).toContain("evalrun_running  running");
+    } finally {
+      outSpy.mockRestore();
+      errSpy.mockRestore();
+    }
+  });
+
+  it("cmdCall --prod sends engineAccess headers", async () => {
+    const slug = resolveProdSlug({ dir: agentDir });
+    backend.setDeployment(slug, runningDetail(slug, engine.url));
+
+    const code = await cmdCall({
+      dir: agentDir,
+      prod: true,
+      team: String(TEAM_ID),
+      apiKey: API_KEY,
+      toolName: "echo",
+      toolInput: '{"message":"hi"}',
+    });
+
+    expect(code).toBe(0);
+    expect(engine.toolHeaders.length).toBe(1);
+    expect(engine.toolHeaders[0]!["x-anyrun-port-token"]).toBe("port-tok-1");
+  });
+});
+
+describe("resolveProdAliasPlaygroundUrl", () => {
+  let backend: MockBackend;
+  const savedEnv: Record<string, string | undefined> = {};
+  let agentDir: string;
+
+  beforeEach(async () => {
+    backend = await startMockBackend();
+    for (const key of [
+      "CURSOR_API_BASE_URL",
+      "CURSOR_API_KEY",
+      "AGENT_SERVE_CONFIG_DIR",
+    ]) {
+      savedEnv[key] = process.env[key];
+    }
+    process.env.CURSOR_API_BASE_URL = backend.url;
+    delete process.env.CURSOR_API_KEY;
+    process.env.AGENT_SERVE_CONFIG_DIR = join(
+      tmpdir(),
+      `agentkit-prod-alias-test-${process.pid}`
+    );
+    agentDir = await mkdtemp(join(tmpdir(), "danny-"));
+  });
+
+  afterEach(async () => {
+    await backend.close();
+    await rm(agentDir, { recursive: true, force: true });
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  it("returns the alias playground URL without requiring engineAccess", async () => {
+    backend.setDeployment("weather", {
+      ...runningDetail("weather", "http://127.0.0.1:9"),
+      engineAccess: null,
+    });
+    const stderr: string[] = [];
+
+    const resolved = await resolveProdAliasPlaygroundUrl({
+      dir: agentDir,
+      slug: "weather",
+      team: String(TEAM_ID),
+      apiKey: API_KEY,
+      err: (text) => stderr.push(text),
+    });
+
+    expect(resolved.slug).toBe("weather");
+    expect(resolved.playgroundUrl).toBe(
+      `${backend.url}/internal/agent-serve/agents/asd_test/engine/playground`
+    );
+    expect(stderr.join("")).toContain('Using hosted deployment "weather".');
+  });
+
+  it("appends sessionId when provided", async () => {
+    backend.setDeployment("weather", {
+      ...runningDetail("weather", "http://127.0.0.1:9"),
+      engineAccess: null,
+    });
+
+    const resolved = await resolveProdAliasPlaygroundUrl({
+      dir: agentDir,
+      slug: "weather",
+      team: String(TEAM_ID),
+      apiKey: API_KEY,
+      sessionId: "ses_abc",
+      err: () => {},
+    });
+
+    expect(resolved.playgroundUrl).toBe(
+      `${backend.url}/internal/agent-serve/agents/asd_test/engine/playground?sessionId=ses_abc`
+    );
+  });
+
+  it("fails when deployment is not running", async () => {
+    backend.setDeployment("weather", {
+      ...runningDetail("weather", "http://127.0.0.1:9"),
+      status: "stopped",
+      engineAccess: null,
+    });
+    await expect(
+      resolveProdAliasPlaygroundUrl({
+        dir: agentDir,
+        slug: "weather",
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+        err: () => {},
+      })
+    ).rejects.toThrow(/stopped, not running/);
+  });
+
+  it("fails when deployment is missing", async () => {
+    await expect(
+      resolveProdAliasPlaygroundUrl({
+        dir: agentDir,
+        slug: "missing",
+        team: String(TEAM_ID),
+        apiKey: API_KEY,
+        err: () => {},
+      })
+    ).rejects.toThrow(/Deployment "missing"/);
+  });
+});