@cursor/july 0.1.19 → 0.1.21

package/src/internal/resolved-connections.test.ts

@@ -0,0 +1,295 @@
+import { describe, expect, it, vi } from "vitest";
+import { httpChannel } from "../channels.js";
+import type { AgentProject, DiscoveredConnection } from "../types.js";
+import { CursorAccountMcpBridge } from "./cursor/account-mcp.js";
+import { CursorBackendClient } from "./cursor/backend-client.js";
+import {
+  assertAccountConnectionsNotAnonymous,
+  assertCloudCanHonorAccountServersFilters,
+  resolveMountConnections,
+  validateMountConnectionsConfig,
+} from "./resolved-connections.js";
+
+function makeProject(
+  overrides: Partial<AgentProject["agent"]> = {},
+  connections: DiscoveredConnection[] = []
+): AgentProject {
+  return {
+    rootDir: "/tmp/resolved-connections-fixture",
+    agentDir: "/tmp/resolved-connections-fixture/agent",
+    name: "fixture",
+    agent: {
+      name: "fixture",
+      runtime: "local",
+      tools: [],
+      skills: [],
+      connections,
+      subagents: [],
+      seedFiles: [],
+      ...overrides,
+    },
+    httpChannel: httpChannel(),
+    channels: [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    diagnostics: [],
+  };
+}
+
+function stubBridge(): CursorAccountMcpBridge {
+  const fetchImpl = vi.fn(async () =>
+    Response.json({ accessToken: "token", refreshToken: "refresh" })
+  );
+  return new CursorAccountMcpBridge({
+    client: new CursorBackendClient({
+      backendUrl: "http://127.0.0.1:9",
+      apiKey: "crsr_test",
+      fetchImpl,
+    }),
+  });
+}
+
+describe("resolveMountConnections", () => {
+  it("refuses cloud-capable agents with filtered account MCP connections and no publicUrl", () => {
+    const project = makeProject({ runtime: "cloud" }, [
+      {
+        name: "cursor",
+        transport: { cursorAccount: true, servers: ["Linear"] },
+      },
+    ]);
+    expect(() =>
+      validateMountConnectionsConfig({
+        slug: "",
+        project,
+        accountRefs: [{ name: "cursor", servers: ["Linear"] }],
+      })
+    ).toThrow(/servers.*filters.*no --public-url/);
+  });
+
+  it("allows cloud-capable agents with unfiltered account MCP connections and no publicUrl", () => {
+    const project = makeProject({ runtime: "cloud" }, [
+      { name: "cursor", transport: { cursorAccount: true } },
+    ]);
+    const warnings: string[] = [];
+    const resolved = resolveMountConnections({
+      slug: "",
+      project,
+      serverUrl: "http://127.0.0.1:4100",
+      accountRefs: [{ name: "cursor" }],
+      accountBridge: stubBridge(),
+      logger: (line) => {
+        warnings.push(line);
+      },
+    });
+    expect(resolved).toHaveLength(1);
+    expect(resolved[0]?.cloudUrl).toBeUndefined();
+    expect(
+      warnings.some((line) => line.includes("omit the account bridge"))
+    ).toBe(true);
+  });
+
+  it("resolves cloudUrl for filtered account MCP connections when publicUrl is set", () => {
+    const project = makeProject({ runtime: "cloud" }, [
+      {
+        name: "cursor",
+        transport: { cursorAccount: true, servers: ["Linear"] },
+      },
+    ]);
+    const resolved = resolveMountConnections({
+      slug: "",
+      project,
+      serverUrl: "http://127.0.0.1:4100",
+      publicUrl: "https://agents.example.com",
+      accountRefs: [{ name: "cursor", servers: ["Linear"] }],
+      accountBridge: stubBridge(),
+      logger: () => {},
+    });
+    expect(resolved[0]?.cloudUrl).toBe(
+      "https://agents.example.com/v1/cursor-account/cursor/mcp"
+    );
+    expect(resolved[0]?.accountServersFilter).toEqual(["Linear"]);
+  });
+
+  it("exempts hostOnly filtered account connections from the publicUrl requirement", () => {
+    // A host-only bridge never reaches the model, so cloud turns have no
+    // `servers` filter to honor — host-side calls always use loopback.
+    const project = makeProject({ runtime: "cloud" }, [
+      {
+        name: "anytool",
+        transport: { cursorAccount: true, servers: ["anytool"] },
+        hostOnly: true,
+      },
+    ]);
+    expect(() =>
+      validateMountConnectionsConfig({
+        slug: "",
+        project,
+        accountRefs: [{ name: "anytool", servers: ["anytool"] }],
+      })
+    ).not.toThrow();
+  });
+
+  it("still refuses when a filtered account connection is not hostOnly", () => {
+    const project = makeProject({ runtime: "cloud" }, [
+      {
+        name: "anytool",
+        transport: { cursorAccount: true, servers: ["anytool"] },
+        hostOnly: true,
+      },
+      {
+        name: "cursor",
+        transport: { cursorAccount: true, servers: ["Linear"] },
+      },
+    ]);
+    expect(() =>
+      validateMountConnectionsConfig({
+        slug: "",
+        project,
+        accountRefs: [
+          { name: "anytool", servers: ["anytool"] },
+          { name: "cursor", servers: ["Linear"] },
+        ],
+      })
+    ).toThrow(/servers.*filters.*no --public-url/);
+  });
+
+  it("warns that cloud turns omit host-OAuth connections", () => {
+    const project = makeProject({ runtime: "cloud" }, [
+      {
+        name: "anytool",
+        transport: { url: "https://anytool.example.com/mcp", oauth: true },
+      },
+    ]);
+    const warnings: string[] = [];
+    resolveMountConnections({
+      slug: "",
+      project,
+      serverUrl: "http://127.0.0.1:4100",
+      logger: (line) => {
+        warnings.push(line);
+      },
+    });
+    expect(
+      warnings.some(
+        (line) =>
+          line.includes("host-OAuth MCP connections (anytool)") &&
+          line.includes("cloud-runtime turns omit them")
+      )
+    ).toBe(true);
+  });
+
+  it("does not warn about host-OAuth connections on local agents or hostOnly ones", () => {
+    const warnings: string[] = [];
+    const logger = (line: string): void => {
+      warnings.push(line);
+    };
+    resolveMountConnections({
+      slug: "",
+      project: makeProject({ runtime: "local" }, [
+        {
+          name: "anytool",
+          transport: { url: "https://anytool.example.com/mcp", oauth: true },
+        },
+      ]),
+      serverUrl: "http://127.0.0.1:4100",
+      logger,
+    });
+    resolveMountConnections({
+      slug: "",
+      project: makeProject({ runtime: "cloud" }, [
+        {
+          name: "anytool",
+          transport: { url: "https://anytool.example.com/mcp", oauth: true },
+          hostOnly: true,
+        },
+      ]),
+      serverUrl: "http://127.0.0.1:4100",
+      logger,
+    });
+    expect(warnings.some((line) => line.includes("host-OAuth"))).toBe(false);
+  });
+
+  it("allows local-default agents with filtered account MCP connections at startup", () => {
+    const project = makeProject({ runtime: "local" }, [
+      {
+        name: "cursor",
+        transport: { cursorAccount: true, servers: ["Linear"] },
+      },
+    ]);
+    const resolved = resolveMountConnections({
+      slug: "",
+      project,
+      serverUrl: "http://127.0.0.1:4100",
+      accountRefs: [{ name: "cursor", servers: ["Linear"] }],
+      accountBridge: stubBridge(),
+      logger: () => {},
+    });
+    expect(resolved).toHaveLength(1);
+    expect(resolved[0]?.cloudUrl).toBeUndefined();
+  });
+});
+
+describe("assertCloudCanHonorAccountServersFilters", () => {
+  it("refuses cloud turns when a filtered account bridge lacks cloudUrl", () => {
+    expect(() =>
+      assertCloudCanHonorAccountServersFilters({
+        runtime: "cloud",
+        resolvedConnections: [
+          {
+            name: "cursor",
+            localUrl: "http://127.0.0.1:4100/v1/cursor-account/cursor/mcp",
+            accountServersFilter: ["Linear"],
+          },
+        ],
+      })
+    ).toThrow(/cannot honor Cursor account `servers` filters/);
+  });
+
+  it("allows local turns without a public bridge URL", () => {
+    expect(() =>
+      assertCloudCanHonorAccountServersFilters({
+        runtime: "local",
+        resolvedConnections: [
+          {
+            name: "cursor",
+            localUrl: "http://127.0.0.1:4100/v1/cursor-account/cursor/mcp",
+            accountServersFilter: ["Linear"],
+          },
+        ],
+      })
+    ).not.toThrow();
+  });
+});
+
+describe("assertAccountConnectionsNotAnonymous", () => {
+  it("refuses anonymous admission when account MCP connections are configured", () => {
+    expect(() =>
+      assertAccountConnectionsNotAnonymous({
+        allowAnonymous: true,
+        hasAccountConnections: true,
+      })
+    ).toThrow(
+      /--allow-anonymous cannot be used with Cursor account MCP connections/
+    );
+  });
+
+  it("allows anonymous admission without account MCP connections", () => {
+    expect(() =>
+      assertAccountConnectionsNotAnonymous({
+        allowAnonymous: true,
+        hasAccountConnections: false,
+      })
+    ).not.toThrow();
+  });
+
+  it("allows anonymous admission when allowAnonymousCursorAccountMcp opts in", () => {
+    expect(() =>
+      assertAccountConnectionsNotAnonymous({
+        allowAnonymous: true,
+        allowAnonymousCursorAccountMcp: true,
+        hasAccountConnections: true,
+      })
+    ).not.toThrow();
+  });
+});

package/src/internal/resolved-connections.ts

@@ -7,7 +7,7 @@
  * connectors instead of the bridge.
  */
 
-import type { AgentProject } from "../types.js";
+import { type AgentProject, isHostOauthConnectionTransport } from "../types.js";
 import {
   type CursorAccountConnectionRef,
   type CursorAccountMcpBridge,
@@ -118,6 +118,23 @@ export function resolveMountConnections(args: {
   const label = args.slug === "" ? args.project.name : args.slug;
   const resolved: EngineResolvedConnection[] = [];
 
+  if (cloudCapable) {
+    const hostOauthNames = agent.connections
+      .filter(
+        (connection) =>
+          connection.hostOnly !== true &&
+          isHostOauthConnectionTransport(connection.transport)
+      )
+      .map((connection) => connection.name);
+    if (hostOauthNames.length > 0) {
+      args.logger(
+        `[agentkit] warning: agent "${label}" has host-OAuth MCP connections (${hostOauthNames.join(
+          ", "
+        )}) whose tokens live on this serve host; cloud-runtime turns omit them. Mark them \`hostOnly: true\` and call them from host tools, or drop \`oauth\` and authorize the server another way.`
+      );
+    }
+  }
+
   if (args.peerRefs !== undefined && args.peerRefs.length > 0) {
     const peers = resolvePeerConnections({
       refs: args.peerRefs,

package/src/internal/router.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { Router, type ServerRoute } from "./router.js";
+
+function route(pattern: string): ServerRoute {
+  return {
+    method: "GET",
+    pattern,
+    auth: "none",
+    handler: () => new Response("ok"),
+  };
+}
+
+describe("Router catch-all segments", () => {
+  it("matches zero or more trailing segments", () => {
+    const router = new Router();
+    router.add(route("/docs/*path"));
+
+    expect(router.match("GET", "/docs")?.params.path).toBe("");
+    expect(router.match("GET", "/docs/")?.params.path).toBe("");
+    expect(router.match("GET", "/docs/quickstart")?.params.path).toBe(
+      "quickstart"
+    );
+    expect(router.match("GET", "/docs/guides/slack")?.params.path).toBe(
+      "guides/slack"
+    );
+    expect(router.match("GET", "/docs/assets/chunks/app.js")?.params.path).toBe(
+      "assets/chunks/app.js"
+    );
+  });
+
+  it("decodes each captured segment", () => {
+    const router = new Router();
+    router.add(route("/docs/*path"));
+    expect(router.match("GET", "/docs/a%20b/c")?.params.path).toBe("a b/c");
+  });
+
+  it("does not shadow unrelated prefixes", () => {
+    const router = new Router();
+    router.add(route("/docs/*path"));
+    expect(router.match("GET", "/v1/health")).toBeUndefined();
+    expect(router.match("GET", "/docsx")).toBeUndefined();
+  });
+
+  it("still matches fixed segments before the catch-all", () => {
+    const router = new Router();
+    router.add(route("/a/:id/*rest"));
+    const match = router.match("GET", "/a/42/x/y");
+    expect(match?.params.id).toBe("42");
+    expect(match?.params.rest).toBe("x/y");
+    expect(router.match("GET", "/a")).toBeUndefined();
+  });
+
+  it("rejects non-trailing catch-alls at registration", () => {
+    const router = new Router();
+    expect(() => router.add(route("/a/*rest/b"))).toThrow(/last segment/);
+  });
+});

package/src/internal/sdk-runner.test.ts

@@ -0,0 +1,290 @@
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { RunnerTurnRequest } from "../types.js";
+import { CursorSdkRunner } from "./sdk-runner.js";
+
+const { createAgent, resumeAgent } = vi.hoisted(() => ({
+  createAgent: vi.fn(),
+  resumeAgent: vi.fn(),
+}));
+
+vi.mock("@cursor/sdk", () => ({
+  Agent: {
+    create: createAgent,
+    resume: resumeAgent,
+  },
+  JsonlLocalAgentStore: class JsonlLocalAgentStore {
+    constructor(readonly path: string) {}
+  },
+}));
+
+describe("CursorSdkRunner", () => {
+  beforeEach(() => {
+    createAgent.mockReset();
+    resumeAgent.mockReset();
+  });
+
+  afterEach(() => {
+    delete process.env.CURSOR_API_KEY;
+  });
+
+  it("creates a local SDK agent when no SDK id was ever bound", async () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    const agent = fakeAgent("ses_retry");
+    createAgent.mockResolvedValue(agent);
+    const runner = new CursorSdkRunner();
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-sdk-runner-"));
+    const onSdkAgentId = vi.fn();
+
+    await runner.runTurn({
+      ...baseRequest(stateRoot),
+      isFirstTurn: false,
+      onSdkAgentId,
+    });
+
+    expect(createAgent).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({ agentId: "ses_retry" })
+    );
+    expect(resumeAgent).not.toHaveBeenCalled();
+    expect(onSdkAgentId).toHaveBeenCalledExactlyOnceWith("ses_retry");
+  });
+
+  it("falls back to a fresh conversation when resume finds no stored agent", async () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    resumeAgent.mockRejectedValue(new Error("Agent ses_retry not found"));
+    createAgent.mockResolvedValue(fakeAgent("ses_retry"));
+    const lines: string[] = [];
+    const runner = new CursorSdkRunner({ logger: (line) => lines.push(line) });
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-sdk-runner-"));
+
+    const outcome = await runner.runTurn({
+      ...baseRequest(stateRoot),
+      isFirstTurn: false,
+      sdkAgentId: "ses_retry",
+    });
+
+    expect(outcome.status).toBe("finished");
+    expect(resumeAgent).toHaveBeenCalledOnce();
+    expect(createAgent).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({ agentId: "ses_retry" })
+    );
+    expect(lines.join("\n")).toContain("fresh");
+  });
+
+  it("propagates resume failures that are not a store miss", async () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    resumeAgent.mockRejectedValue(new Error("transport exploded"));
+    const runner = new CursorSdkRunner();
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-sdk-runner-"));
+
+    await expect(
+      runner.runTurn({
+        ...baseRequest(stateRoot),
+        isFirstTurn: false,
+        sdkAgentId: "ses_retry",
+      })
+    ).rejects.toThrow("transport exploded");
+    expect(createAgent).not.toHaveBeenCalled();
+  });
+
+  it("surfaces the SDK RunResult error message on failed turns", async () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    const agent = {
+      agentId: "ses_retry",
+      send: vi.fn(async () => ({
+        wait: async () => ({
+          status: "error" as const,
+          error: {
+            message:
+              "Authentication error If you are logged in, try logging out and back in.",
+          },
+        }),
+      })),
+    };
+    createAgent.mockResolvedValue(agent);
+    const runner = new CursorSdkRunner();
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-sdk-runner-"));
+
+    const outcome = await runner.runTurn(baseRequest(stateRoot));
+
+    expect(outcome.status).toBe("error");
+    expect(outcome.errorMessage).toBe(
+      "Authentication error If you are logged in, try logging out and back in."
+    );
+    // First turns never retry in place: their token was exchanged moments
+    // ago, so the credential itself is bad and a fresh handle cannot help.
+    expect(agent.send).toHaveBeenCalledTimes(1);
+  });
+
+  it("evicts the cached agent after an error result so the next turn reopens", async () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    const broken = fakeErrorAgent("ses_retry", "model exploded");
+    const healthy = fakeAgent("ses_retry");
+    resumeAgent.mockResolvedValueOnce(broken).mockResolvedValueOnce(healthy);
+    const runner = new CursorSdkRunner();
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-sdk-runner-"));
+    const request = {
+      ...baseRequest(stateRoot),
+      isFirstTurn: false,
+      sdkAgentId: "ses_retry",
+    };
+
+    const first = await runner.runTurn(request);
+    expect(first.status).toBe("error");
+    // Not an auth failure, so no in-place retry.
+    expect(resumeAgent).toHaveBeenCalledTimes(1);
+
+    const second = await runner.runTurn(request);
+    expect(second.status).toBe("finished");
+    expect(resumeAgent).toHaveBeenCalledTimes(2);
+    expect(broken.close).toHaveBeenCalled();
+  });
+
+  it("retries once on a fresh handle when an auth failure precedes any output", async () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    const broken = fakeErrorAgent("ses_retry", AUTH_ERROR_MESSAGE);
+    const healthy = fakeAgent("ses_retry");
+    resumeAgent.mockResolvedValueOnce(broken).mockResolvedValueOnce(healthy);
+    const lines: string[] = [];
+    const runner = new CursorSdkRunner({ logger: (line) => lines.push(line) });
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-sdk-runner-"));
+
+    const outcome = await runner.runTurn({
+      ...baseRequest(stateRoot),
+      isFirstTurn: false,
+      sdkAgentId: "ses_retry",
+    });
+
+    expect(outcome.status).toBe("finished");
+    expect(resumeAgent).toHaveBeenCalledTimes(2);
+    expect(broken.close).toHaveBeenCalled();
+    expect(lines.join("\n")).toContain("retrying the turn");
+  });
+
+  it("does not retry an auth failure once the turn has streamed output", async () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    const broken = {
+      agentId: "ses_retry",
+      close: vi.fn(),
+      send: vi.fn(
+        async (
+          _prompt: string,
+          options: { onDelta: (event: { update: unknown }) => Promise<void> }
+        ) => {
+          await options.onDelta({ update: { kind: "assistant" } });
+          return {
+            wait: async () => ({
+              status: "error" as const,
+              error: { message: AUTH_ERROR_MESSAGE },
+            }),
+          };
+        }
+      ),
+    };
+    resumeAgent.mockResolvedValue(broken);
+    const runner = new CursorSdkRunner();
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-sdk-runner-"));
+
+    const outcome = await runner.runTurn({
+      ...baseRequest(stateRoot),
+      isFirstTurn: false,
+      sdkAgentId: "ses_retry",
+    });
+
+    expect(outcome.status).toBe("error");
+    expect(outcome.errorMessage).toBe(AUTH_ERROR_MESSAGE);
+    expect(resumeAgent).toHaveBeenCalledTimes(1);
+    expect(broken.send).toHaveBeenCalledTimes(1);
+  });
+
+  it("recycles a handle older than the age budget onto a fresh open", async () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    vi.useFakeTimers({
+      now: new Date("2026-07-28T00:00:00Z"),
+      toFake: ["Date"],
+    });
+    try {
+      const early = fakeAgent("ses_retry");
+      const late = fakeAgent("ses_retry");
+      resumeAgent.mockResolvedValueOnce(early).mockResolvedValueOnce(late);
+      const runner = new CursorSdkRunner();
+      const stateRoot = await mkdtemp(
+        join(tmpdir(), "agent-serve-sdk-runner-")
+      );
+      const request = {
+        ...baseRequest(stateRoot),
+        isFirstTurn: false,
+        sdkAgentId: "ses_retry",
+      };
+
+      await runner.runTurn(request);
+      // Within the budget the handle is reused.
+      vi.setSystemTime(new Date("2026-07-28T00:30:00Z"));
+      await runner.runTurn(request);
+      expect(resumeAgent).toHaveBeenCalledTimes(1);
+      expect(early.send).toHaveBeenCalledTimes(2);
+
+      // Past the budget (45 min) the handle is retired before the send, so
+      // the exchanged access token (60 min lifetime) can never expire
+      // mid-session.
+      vi.setSystemTime(new Date("2026-07-28T00:46:00Z"));
+      await runner.runTurn(request);
+      expect(resumeAgent).toHaveBeenCalledTimes(2);
+      expect(late.send).toHaveBeenCalledTimes(1);
+      expect(early.close).toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+const AUTH_ERROR_MESSAGE =
+  "Authentication error If you are logged in, try logging out and back in.";
+
+function fakeAgent(agentId: string): {
+  agentId: string;
+  send: ReturnType<typeof vi.fn>;
+  close: ReturnType<typeof vi.fn>;
+} {
+  return {
+    agentId,
+    send: vi.fn(async () => ({
+      wait: async () => ({ status: "finished", result: "ok" }),
+    })),
+    close: vi.fn(),
+  };
+}
+
+function fakeErrorAgent(
+  agentId: string,
+  message: string
+): {
+  agentId: string;
+  send: ReturnType<typeof vi.fn>;
+  close: ReturnType<typeof vi.fn>;
+} {
+  return {
+    agentId,
+    send: vi.fn(async () => ({
+      wait: async () => ({ status: "error", error: { message } }),
+    })),
+    close: vi.fn(),
+  };
+}
+
+function baseRequest(stateRoot: string): RunnerTurnRequest {
+  return {
+    sessionId: "ses_retry",
+    workspaceDir: stateRoot,
+    runnerStateDir: join(stateRoot, "runner"),
+    prompt: "hello",
+    isFirstTurn: true,
+    runtime: "local",
+    customTools: {},
+    mcpServers: {},
+    subagents: [],
+    onUpdate: () => {},
+  };
+}