@cursor/july 0.1.19 → 0.1.21

package/src/internal/mcp-endpoint.test.ts

@@ -0,0 +1,436 @@
+import { describe, expect, it, vi } from "vitest";
+import { httpChannel } from "../channels.js";
+import { defineTool } from "../tools.js";
+import type {
+  AgentProject,
+  AuthContext,
+  SessionRecord,
+  ToolCallOutcome,
+  TurnOutcome,
+} from "../types.js";
+import {
+  createAgentMcpEndpoint,
+  MCP_CHANNEL_ID,
+  mcpEndpointToolNames,
+} from "./mcp-endpoint.js";
+import type { SessionEngine } from "./session-engine.js";
+import { UnknownToolError } from "./session-engine.js";
+
+const LOCAL_AUTH: AuthContext = {
+  authenticator: "local-dev-strict",
+  principalId: "local",
+  principalType: "user",
+};
+
+function makeProject(
+  overrides: { serverTools?: boolean; description?: string } = {}
+): AgentProject {
+  const tools =
+    overrides.serverTools === true
+      ? [
+          {
+            name: "get_number",
+            description: "Return a number.",
+            execution: "server" as const,
+            needsApproval: false,
+            inputSchema: { type: "object" },
+            definition: defineTool({
+              description: "Return a number.",
+              async execute() {
+                return { value: 42 };
+              },
+            }),
+          },
+        ]
+      : [];
+  return {
+    rootDir: "/tmp/mcp-endpoint-fixture",
+    agentDir: "/tmp/mcp-endpoint-fixture/agent",
+    name: "fixture-agent",
+    agent: {
+      name: "fixture-agent",
+      ...(overrides.description === undefined
+        ? {}
+        : { description: overrides.description }),
+      runtime: "local",
+      tools,
+      skills: [],
+      connections: [],
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    diagnostics: [],
+  };
+}
+
+interface EngineStub {
+  project: AgentProject;
+  send: ReturnType<typeof vi.fn>;
+  sessions: { get: ReturnType<typeof vi.fn> };
+  waitForCompletion: ReturnType<typeof vi.fn>;
+  listEvents: ReturnType<typeof vi.fn>;
+  callTool: ReturnType<typeof vi.fn>;
+}
+
+function makeEngine(
+  overrides: Partial<{
+    project: AgentProject;
+    record: SessionRecord | undefined;
+    outcome: TurnOutcome | Promise<TurnOutcome>;
+  }> = {}
+): EngineStub {
+  return {
+    project: overrides.project ?? makeProject(),
+    send: vi.fn(async () => ({
+      id: "ses_new",
+      continuationToken: "cont",
+      isNew: true,
+    })),
+    sessions: { get: vi.fn(async () => overrides.record) },
+    waitForCompletion: vi.fn(
+      () =>
+        overrides.outcome ??
+        Promise.resolve({ status: "finished", result: "the reply" })
+    ),
+    listEvents: vi.fn(async () => []),
+    callTool: vi.fn(async (): Promise<ToolCallOutcome> => {
+      throw new Error("not stubbed");
+    }),
+  };
+}
+
+function sessionRecord(overrides: Partial<SessionRecord> = {}): SessionRecord {
+  const now = new Date().toISOString();
+  return {
+    sessionId: "ses_existing",
+    channelId: MCP_CHANNEL_ID,
+    mode: "chat",
+    continuationKey: "cont_key",
+    auth: LOCAL_AUTH,
+    turnCount: 1,
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+function rpcRequest(body: unknown): Request {
+  return new Request("http://127.0.0.1:3000/v1/mcp", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+function toolCallRequest(name: string, args: unknown, id = 1): Request {
+  return rpcRequest({
+    jsonrpc: "2.0",
+    id,
+    method: "tools/call",
+    params: { name, arguments: args },
+  });
+}
+
+async function rpcResult(response: Response): Promise<{
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+}> {
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as {
+    result?: {
+      content: Array<{ type: string; text: string }>;
+      isError?: boolean;
+    };
+    error?: { message: string };
+  };
+  expect(body.error).toBeUndefined();
+  return body.result!;
+}
+
+function payloadOf(result: { content: Array<{ text: string }> }): {
+  status: string;
+  sessionId: string;
+  reply?: string;
+  errorMessage?: string;
+} {
+  return JSON.parse(result.content[0]!.text) as ReturnType<typeof payloadOf>;
+}
+
+describe("createAgentMcpEndpoint", () => {
+  it("responds to initialize with the agent identity and instructions", async () => {
+    const engine = makeEngine({
+      project: makeProject({ description: "Answers weather questions." }),
+    });
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+    const response = await endpoint.handle(
+      rpcRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2025-03-26",
+          capabilities: {},
+          clientInfo: { name: "test", version: "0.0.0" },
+        },
+      }),
+      LOCAL_AUTH
+    );
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as {
+      result: { serverInfo: { name: string }; instructions?: string };
+    };
+    expect(body.result.serverInfo.name).toBe("fixture-agent");
+    expect(body.result.instructions).toContain("Answers weather questions.");
+    expect(body.result.instructions).toContain("ask");
+  });
+
+  it("lists ask/check, and call_tool only when server tools exist", async () => {
+    const bare = makeEngine();
+    const withTools = makeEngine({
+      project: makeProject({ serverTools: true }),
+    });
+    for (const [engine, expectCallTool] of [
+      [bare, false],
+      [withTools, true],
+    ] as const) {
+      const endpoint = createAgentMcpEndpoint({
+        engine: engine as unknown as SessionEngine,
+      });
+      const response = await endpoint.handle(
+        rpcRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" }),
+        LOCAL_AUTH
+      );
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as {
+        result: { tools: Array<{ name: string }> };
+      };
+      const names = body.result.tools.map((tool) => tool.name).sort();
+      expect(names).toEqual(
+        expectCallTool ? ["ask", "call_tool", "check"] : ["ask", "check"]
+      );
+    }
+    expect(mcpEndpointToolNames(bare.project)).toEqual(["ask", "check"]);
+    expect(mcpEndpointToolNames(withTools.project)).toEqual([
+      "ask",
+      "check",
+      "call_tool",
+    ]);
+  });
+
+  it("ask starts a session on the mcp channel bound to the caller and returns the reply", async () => {
+    const engine = makeEngine();
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+    const response = await endpoint.handle(
+      toolCallRequest("ask", { message: "hello" }),
+      LOCAL_AUTH
+    );
+    const result = await rpcResult(response);
+    const payload = payloadOf(result);
+    expect(payload).toMatchObject({
+      status: "completed",
+      sessionId: "ses_new",
+      reply: "the reply",
+    });
+    expect(engine.send).toHaveBeenCalledWith(MCP_CHANNEL_ID, "hello", {
+      auth: LOCAL_AUTH,
+    });
+  });
+
+  it("ask returns status running when the turn outlives waitSeconds", async () => {
+    const engine = makeEngine({
+      outcome: new Promise<TurnOutcome>(() => {}),
+    });
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+    const response = await endpoint.handle(
+      toolCallRequest("ask", { message: "slow", waitSeconds: 0 }),
+      LOCAL_AUTH
+    );
+    const payload = payloadOf(await rpcResult(response));
+    expect(payload.status).toBe("running");
+    expect(payload.sessionId).toBe("ses_new");
+  });
+
+  it("ask follows up on an owned session without rotating its continuation", async () => {
+    const record = sessionRecord();
+    const engine = makeEngine({ record });
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+    const response = await endpoint.handle(
+      toolCallRequest("ask", { message: "more", sessionId: "ses_existing" }),
+      LOCAL_AUTH
+    );
+    const payload = payloadOf(await rpcResult(response));
+    expect(payload).toMatchObject({
+      status: "completed",
+      sessionId: "ses_existing",
+    });
+    expect(engine.send).toHaveBeenCalledWith(MCP_CHANNEL_ID, "more", {
+      auth: record.auth,
+      continuationToken: "cont_key",
+    });
+  });
+
+  it("ask rejects follow-ups from a different principal", async () => {
+    const engine = makeEngine({
+      record: sessionRecord({
+        auth: {
+          authenticator: "bearer",
+          principalId: "bearer",
+          principalType: "service",
+        },
+      }),
+    });
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+    const response = await endpoint.handle(
+      toolCallRequest("ask", { message: "hi", sessionId: "ses_existing" }),
+      LOCAL_AUTH
+    );
+    const result = await rpcResult(response);
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain("different principal");
+    expect(engine.send).not.toHaveBeenCalled();
+  });
+
+  it("ask rejects follow-ups on task sessions", async () => {
+    const engine = makeEngine({
+      record: sessionRecord({ mode: "task" }),
+    });
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+    const response = await endpoint.handle(
+      toolCallRequest("ask", { message: "hi", sessionId: "ses_existing" }),
+      LOCAL_AUTH
+    );
+    const result = await rpcResult(response);
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain("task session");
+  });
+
+  it("check waits for an owned session and reports errors as isError", async () => {
+    const engine = makeEngine({
+      record: sessionRecord(),
+      outcome: Promise.resolve({
+        status: "error",
+        errorMessage: "boom",
+      } satisfies TurnOutcome),
+    });
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+    const response = await endpoint.handle(
+      toolCallRequest("check", { sessionId: "ses_existing" }),
+      LOCAL_AUTH
+    );
+    const result = await rpcResult(response);
+    expect(result.isError).toBe(true);
+    expect(payloadOf(result)).toMatchObject({
+      status: "error",
+      errorMessage: "boom",
+    });
+  });
+
+  it("check recovers the reply from the event log after a restart", async () => {
+    const engine = makeEngine({
+      record: sessionRecord(),
+      outcome: Promise.resolve({ status: "finished" } satisfies TurnOutcome),
+    });
+    engine.listEvents.mockResolvedValue([
+      {
+        type: "turn.completed",
+        index: 3,
+        sessionId: "ses_existing",
+        at: new Date().toISOString(),
+        data: { result: "recovered reply" },
+      },
+    ]);
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+    const response = await endpoint.handle(
+      toolCallRequest("check", { sessionId: "ses_existing" }),
+      LOCAL_AUTH
+    );
+    const payload = payloadOf(await rpcResult(response));
+    expect(payload).toMatchObject({
+      status: "completed",
+      reply: "recovered reply",
+    });
+  });
+
+  it("call_tool passes through to engine.callTool and surfaces unknown tools", async () => {
+    const engine = makeEngine({ project: makeProject({ serverTools: true }) });
+    engine.callTool.mockResolvedValue({
+      toolName: "get_number",
+      callId: "tool_get_number_1",
+      isError: false,
+      result: { value: 42 },
+      durationMs: 3,
+    } satisfies ToolCallOutcome);
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+
+    const okResponse = await endpoint.handle(
+      toolCallRequest("call_tool", {
+        toolName: "get_number",
+        input: { seed: 1 },
+      }),
+      LOCAL_AUTH
+    );
+    const okResult = await rpcResult(okResponse);
+    expect(okResult.isError).toBeUndefined();
+    expect(JSON.parse(okResult.content[0]!.text)).toMatchObject({
+      toolName: "get_number",
+      result: { value: 42 },
+    });
+    expect(engine.callTool).toHaveBeenCalledWith(
+      "get_number",
+      { seed: 1 },
+      { auth: LOCAL_AUTH }
+    );
+
+    engine.callTool.mockRejectedValue(
+      new UnknownToolError("nope", ["get_number"])
+    );
+    const errResponse = await endpoint.handle(
+      toolCallRequest("call_tool", { toolName: "nope" }, 2),
+      LOCAL_AUTH
+    );
+    const errResult = await rpcResult(errResponse);
+    expect(errResult.isError).toBe(true);
+    expect(errResult.content[0]!.text).toContain("get_number");
+  });
+
+  it("rejects non-POST methods with 405", async () => {
+    const engine = makeEngine();
+    const endpoint = createAgentMcpEndpoint({
+      engine: engine as unknown as SessionEngine,
+    });
+    for (const method of ["GET", "DELETE"]) {
+      const response = await endpoint.handle(
+        new Request("http://127.0.0.1:3000/v1/mcp", { method }),
+        LOCAL_AUTH
+      );
+      expect(response.status).toBe(405);
+      expect(response.headers.get("allow")).toBe("POST");
+    }
+  });
+});