@cursor/july 0.1.19 → 0.1.21

package/src/internal/peer-mcp.integration.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Integration: agent-to-agent communication over the real wire path.
+ *
+ * Two agents are mounted on one server. The "concierge" has a peer
+ * connection to the "helper"; its (mock) runner behaves like the harness
+ * and connects a real MCP SDK client to the resolved peer URL, calls
+ * `ask`, and folds the helper's reply into its own result. The helper's
+ * (mock) runner answers instantly. Everything in between — route auth,
+ * the streamable-HTTP MCP endpoint, session creation on the `mcp`
+ * channel, turn execution, reply plumbing — is the production code path.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { afterEach, describe, expect, it } from "vitest";
+import { httpChannel } from "../channels.js";
+import type {
+  AgentProject,
+  AgentServeHandle,
+  ConnectionTransport,
+  RunnerTurnRequest,
+  SessionSummary,
+} from "../types.js";
+import { MCP_CHANNEL_ID } from "./mcp-endpoint.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { startServer } from "./server.js";
+
+function makeProject(
+  name: string,
+  options: {
+    connections?: Array<{ name: string; transport: ConnectionTransport }>;
+    runtime?: "local" | "cloud";
+    cloud?: AgentProject["agent"]["cloud"];
+  } = {}
+): AgentProject {
+  return {
+    rootDir: `/tmp/peer-fixture-${name}`,
+    agentDir: `/tmp/peer-fixture-${name}/agent`,
+    name,
+    agent: {
+      name,
+      description: `The ${name} fixture agent.`,
+      runtime: options.runtime ?? "local",
+      ...(options.cloud === undefined ? {} : { cloud: options.cloud }),
+      tools: [],
+      skills: [],
+      connections: options.connections ?? [],
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    diagnostics: [],
+  };
+}
+
+interface AskAnswer {
+  status: string;
+  reply?: string;
+  sessionId: string;
+}
+
+async function askViaMcp(url: string, message: string): Promise<AskAnswer> {
+  const client = new Client({ name: "peer-test", version: "0.0.0" });
+  const transport = new StreamableHTTPClientTransport(new URL(url));
+  await client.connect(transport);
+  try {
+    const result = (await client.callTool({
+      name: "ask",
+      arguments: { message },
+    })) as { content: Array<{ type: string; text: string }> };
+    return JSON.parse(result.content[0]?.text ?? "{}") as AskAnswer;
+  } finally {
+    await client.close();
+  }
+}
+
+async function postSession(
+  base: string,
+  message: string
+): Promise<{ sessionId: string }> {
+  const response = await fetch(`${base}/v1/session`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ message }),
+  });
+  expect(response.status).toBe(200);
+  return (await response.json()) as { sessionId: string };
+}
+
+async function listSessions(base: string): Promise<SessionSummary[]> {
+  const response = await fetch(`${base}/v1/sessions`);
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as { sessions: SessionSummary[] };
+  return body.sessions;
+}
+
+async function waitForIdleSession(
+  base: string,
+  sessionId: string
+): Promise<SessionSummary> {
+  for (let i = 0; i < 200; i++) {
+    const sessions = await listSessions(base);
+    const session = sessions.find((s) => s.sessionId === sessionId);
+    if (session !== undefined && !session.running) {
+      return session;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error(`session ${sessionId} never went idle`);
+}
+
+async function readEvents(
+  base: string,
+  sessionId: string
+): Promise<Array<{ type: string; data: Record<string, unknown> }>> {
+  const response = await fetch(
+    `${base}/v1/session/${sessionId}/events?format=json`
+  );
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as {
+    events: Array<{ type: string; data: Record<string, unknown> }>;
+  };
+  return body.events;
+}
+
+describe("peer MCP connections over the MCP endpoint (integration)", () => {
+  let stateRoot: string | undefined;
+  let handle: AgentServeHandle | undefined;
+
+  afterEach(async () => {
+    await handle?.close();
+    handle = undefined;
+    if (stateRoot !== undefined) {
+      await rm(stateRoot, { recursive: true, force: true });
+      stateRoot = undefined;
+    }
+  });
+
+  it("concierge delegates to helper through the real MCP wire path", async () => {
+    stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-peer-"));
+
+    const helperSeen: string[] = [];
+    const runner: AgentRunner = {
+      async runTurn(request: RunnerTurnRequest) {
+        const peer = request.mcpServers.helper;
+        if (peer !== undefined) {
+          // Concierge turn: reach the helper exactly like the harness
+          // would — a real MCP client against the resolved peer URL.
+          if (!("url" in peer)) {
+            throw new Error("peer transport was not resolved to a URL");
+          }
+          const answer = await askViaMcp(peer.url, "What is 2+2?");
+          expect(answer.status).toBe("completed");
+          return {
+            status: "finished",
+            result: `helper says: ${answer.reply ?? "(no reply)"}`,
+          };
+        }
+        // Helper turn.
+        helperSeen.push(request.prompt);
+        return { status: "finished", result: "the answer is 4" };
+      },
+    };
+
+    handle = await startServer(
+      [
+        {
+          slug: "concierge",
+          project: makeProject("concierge", {
+            connections: [
+              { name: "helper", transport: { agent: "helper" } },
+              // A concrete connection must survive peer merging untouched.
+              {
+                name: "linear",
+                transport: { url: "https://mcp.example.com/mcp" },
+              },
+            ],
+          }),
+        },
+        { slug: "helper", project: makeProject("helper") },
+      ],
+      { port: 0, stateRoot, runner, playground: false }
+    );
+
+    const conciergeBase = `${handle.url}/concierge`;
+    const helperBase = `${handle.url}/helper`;
+
+    const { sessionId } = await postSession(conciergeBase, "ask the helper");
+    await waitForIdleSession(conciergeBase, sessionId);
+
+    const events = await readEvents(conciergeBase, sessionId);
+    const completed = events.find((event) => event.type === "turn.completed");
+    expect(completed?.data.result).toBe("helper says: the answer is 4");
+
+    // The helper ran a real session of its own on the mcp channel; its first
+    // turn carries the framework session-context block before the message.
+    expect(helperSeen).toHaveLength(1);
+    expect(helperSeen[0]).toMatch(/^<agentkit_context>\n/);
+    expect(helperSeen[0]?.endsWith("\n\nWhat is 2+2?")).toBe(true);
+    const helperSessions = await listSessions(helperBase);
+    expect(helperSessions).toHaveLength(1);
+    expect(helperSessions[0]?.channelId).toBe(MCP_CHANNEL_ID);
+  });
+
+  it("selects the cloud URL for cloud turns and omits peers without a publicUrl", async () => {
+    stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-peer-cloud-"));
+
+    const seenMcpServers: Array<Record<string, ConnectionTransport>> = [];
+    const runner: AgentRunner = {
+      async runTurn(request: RunnerTurnRequest) {
+        seenMcpServers.push(request.mcpServers);
+        return { status: "finished", result: "ok" };
+      },
+    };
+
+    const mounts = [
+      {
+        slug: "cloudy",
+        project: makeProject("cloudy", {
+          runtime: "cloud" as const,
+          cloud: { repos: [{ url: "https://github.com/org/repo" }] },
+          connections: [{ name: "helper", transport: { agent: "helper" } }],
+        }),
+      },
+      { slug: "helper", project: makeProject("helper") },
+    ];
+
+    // Without a publicUrl the peer is omitted from the cloud turn.
+    const warnings: string[] = [];
+    handle = await startServer(mounts, {
+      port: 0,
+      stateRoot: join(stateRoot, "without"),
+      runner,
+      playground: false,
+      logger: (line) => {
+        warnings.push(line);
+      },
+    });
+    const withoutSession = await postSession(
+      `${handle.url}/cloudy`,
+      "go cloud"
+    );
+    await waitForIdleSession(`${handle.url}/cloudy`, withoutSession.sessionId);
+    expect(seenMcpServers[0]?.helper).toBeUndefined();
+    expect(warnings.some((line) => line.includes("no --public-url"))).toBe(
+      true
+    );
+    await handle.close();
+
+    // With a publicUrl the peer resolves to the public MCP URL.
+    handle = await startServer(mounts, {
+      port: 0,
+      stateRoot: join(stateRoot, "with"),
+      runner,
+      playground: false,
+      publicUrl: "https://agents.example.com",
+    });
+    const withSession = await postSession(`${handle.url}/cloudy`, "go cloud");
+    await waitForIdleSession(`${handle.url}/cloudy`, withSession.sessionId);
+    const peer = seenMcpServers[1]?.helper;
+    expect(peer).toEqual({
+      url: "https://agents.example.com/helper/v1/mcp",
+    });
+  });
+
+  it("refuses to start on unknown peer slugs", async () => {
+    stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-peer-bad-"));
+    await expect(
+      startServer(
+        [
+          {
+            slug: "concierge",
+            project: makeProject("concierge", {
+              connections: [{ name: "ghost", transport: { agent: "missing" } }],
+            }),
+          },
+        ],
+        { port: 0, stateRoot, playground: false }
+      )
+    ).rejects.toThrow(/unknown peer agent "missing"/);
+  });
+});

package/src/internal/playground/toolchain.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  packageRoot,
+  playgroundDevBaseFromEnv,
+  playgroundDevBasePath,
+  playgroundDevPort,
+  playgroundToolchainAvailable,
+  resolvePlaygroundToolchain,
+} from "./toolchain.js";
+
+describe("playground toolchain", () => {
+  it("resolves the agent-serve package root", () => {
+    const root = packageRoot().replace(/\/$/, "");
+    expect(root.endsWith("packages/agent-serve")).toBe(true);
+  });
+
+  it("detects the local vite toolchain in this checkout", () => {
+    expect(playgroundToolchainAvailable()).toBe(true);
+    const toolchain = resolvePlaygroundToolchain();
+    expect(toolchain).toBeDefined();
+    expect(toolchain?.viteCli).toContain("vite");
+    expect(toolchain?.viteConfig).toContain("playground/vite.config.ts");
+  });
+
+  it("defaults invalid AGENT_SERVE_PLAYGROUND_PORT to 5273", () => {
+    vi.stubEnv("AGENT_SERVE_PLAYGROUND_PORT", "not-a-port");
+    expect(playgroundDevPort()).toBe(5273);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("picks AGENT_SERVE_BASE only for a single slugged mount", () => {
+    expect(playgroundDevBasePath([{ slug: "fsd" }])).toBe("/fsd");
+    expect(playgroundDevBasePath([{ slug: "" }])).toBeUndefined();
+    expect(
+      playgroundDevBasePath([{ slug: "fsd" }, { slug: "bugbot" }])
+    ).toBeUndefined();
+    expect(playgroundDevBasePath([])).toBeUndefined();
+  });
+
+  it("normalizes AGENT_SERVE_BASE from the environment", () => {
+    expect(playgroundDevBaseFromEnv({})).toBeUndefined();
+    expect(playgroundDevBaseFromEnv({ AGENT_SERVE_BASE: "" })).toBeUndefined();
+    expect(playgroundDevBaseFromEnv({ AGENT_SERVE_BASE: "/" })).toBeUndefined();
+    expect(playgroundDevBaseFromEnv({ AGENT_SERVE_BASE: "/fsd" })).toBe("/fsd");
+    expect(playgroundDevBaseFromEnv({ AGENT_SERVE_BASE: "fsd/" })).toBe("/fsd");
+    expect(
+      playgroundDevBaseFromEnv({ AGENT_SERVE_BASE: "  /weather-agent  " })
+    ).toBe("/weather-agent");
+  });
+});

package/src/internal/playground-cli.test.ts

@@ -0,0 +1,187 @@
+import { createServer, type Server } from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cmdPlayground } from "./cli-ax.js";
+import * as openBrowserMod from "./open-browser.js";
+import * as playgroundProxy from "./playground-proxy.js";
+import * as resolveProdTarget from "./resolve-prod-target.js";
+
+const servers: Server[] = [];
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(
+    servers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          server.close(() => resolve());
+        })
+    )
+  );
+});
+
+function listen(
+  handler: (
+    req: import("node:http").IncomingMessage,
+    res: import("node:http").ServerResponse
+  ) => void
+): Promise<string> {
+  const server = createServer(handler);
+  servers.push(server);
+  return new Promise((resolve, reject) => {
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (address === null || typeof address === "string") {
+        reject(new Error("expected AddressInfo"));
+        return;
+      }
+      resolve(`http://127.0.0.1:${address.port}`);
+    });
+  });
+}
+
+describe("cmdPlayground", () => {
+  it("prints a direct local URL without starting a proxy", async () => {
+    const openSpy = vi
+      .spyOn(openBrowserMod, "openBrowser")
+      .mockImplementation(() => {});
+    const startSpy = vi.spyOn(playgroundProxy, "startPlaygroundProxy");
+
+    const stdout: string[] = [];
+    vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+      stdout.push(String(chunk));
+      return true;
+    });
+
+    const code = await cmdPlayground({
+      dir: ".",
+      url: "http://127.0.0.1:3000",
+      print: true,
+    });
+
+    expect(code).toBe(0);
+    expect(stdout.join("")).toContain("http://127.0.0.1:3000/playground");
+    expect(openSpy).not.toHaveBeenCalled();
+    expect(startSpy).not.toHaveBeenCalled();
+  });
+
+  it("injects bearer via proxy so /playground is reachable", async () => {
+    vi.spyOn(openBrowserMod, "openBrowser").mockImplementation(() => {});
+
+    let seenAuth: string | undefined;
+    const upstream = await listen((req, res) => {
+      seenAuth = req.headers.authorization;
+      res.writeHead(200, { "content-type": "text/html" });
+      res.end("<html>ok</html>");
+    });
+
+    const stdout: string[] = [];
+    vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+      stdout.push(String(chunk));
+      return true;
+    });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const ac = new AbortController();
+    const run = cmdPlayground({
+      dir: ".",
+      url: upstream,
+      bearerToken: "cli-secret",
+      print: true,
+      signal: ac.signal,
+    });
+
+    await new Promise((r) => setTimeout(r, 30));
+    const match = stdout
+      .join("")
+      .match(/http:\/\/127\.0\.0\.1:\d+\/playground\?proxyToken=[^\s]+/);
+    expect(match).not.toBeNull();
+
+    // Follow the bootstrap redirect (sets cookie) then load playground.
+    const jar = new Map<string, string>();
+    const first = await fetch(match![0]!, { redirect: "manual" });
+    expect(first.status).toBe(302);
+    const setCookie = first.headers.get("set-cookie") ?? "";
+    const cookieMatch = setCookie.match(/agentkit_playground_proxy=([^;]+)/);
+    expect(cookieMatch).not.toBeNull();
+    jar.set("agentkit_playground_proxy", cookieMatch![1]!);
+
+    const location = first.headers.get("location") ?? "/playground";
+    const localOrigin = new URL(match![0]!).origin;
+    const resp = await fetch(`${localOrigin}${location}`, {
+      headers: {
+        cookie: [...jar.entries()].map(([k, v]) => `${k}=${v}`).join("; "),
+      },
+    });
+    expect(resp.status).toBe(200);
+    expect(seenAuth).toBe("Bearer cli-secret");
+
+    ac.abort();
+    expect(await run).toBe(0);
+  });
+
+  it("opens the hosted alias playground for --prod without a proxy", async () => {
+    const openSpy = vi
+      .spyOn(openBrowserMod, "openBrowser")
+      .mockImplementation(() => {});
+    const startSpy = vi.spyOn(playgroundProxy, "startPlaygroundProxy");
+    const resolveSpy = vi
+      .spyOn(resolveProdTarget, "resolveProdAliasPlaygroundUrl")
+      .mockResolvedValue({
+        playgroundUrl:
+          "https://api.cursor.com/internal/agent-serve/agents/asd_test/engine/playground",
+        slug: "weather",
+      });
+
+    const stdout: string[] = [];
+    vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+      stdout.push(String(chunk));
+      return true;
+    });
+
+    const code = await cmdPlayground({
+      dir: ".",
+      prod: true,
+      slug: "weather",
+      team: "42",
+      print: true,
+    });
+
+    expect(code).toBe(0);
+    expect(stdout.join("")).toContain(
+      "https://api.cursor.com/internal/agent-serve/agents/asd_test/engine/playground"
+    );
+    expect(openSpy).not.toHaveBeenCalled();
+    expect(startSpy).not.toHaveBeenCalled();
+    expect(resolveSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        slug: "weather",
+        team: "42",
+      })
+    );
+  });
+
+  it("passes --session through to the alias playground URL", async () => {
+    vi.spyOn(openBrowserMod, "openBrowser").mockImplementation(() => {});
+    const resolveSpy = vi
+      .spyOn(resolveProdTarget, "resolveProdAliasPlaygroundUrl")
+      .mockResolvedValue({
+        playgroundUrl:
+          "https://api.cursor.com/internal/agent-serve/agents/asd_test/engine/playground?sessionId=ses_1",
+        slug: "weather",
+      });
+    vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+
+    const code = await cmdPlayground({
+      dir: ".",
+      prod: true,
+      slug: "weather",
+      sessionId: "ses_1",
+      print: true,
+    });
+
+    expect(code).toBe(0);
+    expect(resolveSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: "ses_1" })
+    );
+  });
+});