Skip to content

πŸ™Œ OpenHands: AI-Driven Development

20.8 KB
Raw Blame
import { beforeEach, describe, expect, it, vi } from "vitest";
import { CANVAS_UI_CLIENT_TOOL_NAME } from "#/constants/canvas-ui";
import { LAUNCH_CHILD_CONVERSATION_TOOL_NAME } from "#/constants/child-conversation";
import { REQUEST_SECRET_TOOL_NAME } from "#/constants/secret-request";
import { DEFAULT_SETTINGS } from "#/services/settings";
import type { Settings } from "#/types/settings";
import {
  ACP_SERVER_TAG_KEY,
  AGENT_CANVAS_SOURCE,
  CLIENT_SOURCE_TAG_KEY,
  buildStartConversationRequest,
  buildStartPlanningConversationRequest,
  buildStartPlanningConversationRequestWithEncryptedSettings,
  toConversationPage,
} from "./agent-server-adapter";
import SettingsService from "./settings-service/settings-service.api";
import AgentProfilesService from "./agent-profiles-service/agent-profiles-service.api";
import ProfilesService from "./profiles-service/profiles-service.api";

vi.mock("./settings-service/settings-service.api", () => ({
  default: { getSettingsForConversation: vi.fn() },
}));
vi.mock("./secrets-service", () => ({
  SecretsService: { getSecrets: vi.fn().mockResolvedValue([]) },
}));
vi.mock("./agent-profiles-service/agent-profiles-service.api", () => ({
  default: { listProfiles: vi.fn(), getProfile: vi.fn() },
}));
vi.mock("./profiles-service/profiles-service.api", () => ({
  default: { getProfile: vi.fn() },
}));

function makeSettings(agentSettings: Settings["agent_settings"]): Settings {
  return {
    ...DEFAULT_SETTINGS,
    agent_settings: agentSettings,
    conversation_settings: {
      confirmation_mode: false,
      security_analyzer: null,
      max_iterations: 20,
    },
  };
}

function getPlannerAgentContextSkillNames(payload: {
  agent: { agent_context?: { skills?: Array<{ name?: string }> } };
}): Array<string | undefined> {
  return payload.agent.agent_context?.skills?.map((skill) => skill.name) ?? [];
}

describe("buildStartConversationRequest", () => {
  it("builds a raw planning agent request for local Planner", () => {
    const agentSettings = {
      agent_kind: "openhands",
      llm: {
        model: "openhands/minimax-m2.7",
        api_key: "gAAAAAencrypted-llm-api-key",
      },
    };

    const payload = buildStartPlanningConversationRequest({
      encryptedAgentSettings: agentSettings,
      workingDir: "/workspace/project/agent-canvas",
      parentConversationId: "parent-1",
      secretsEncrypted: true,
      customSecrets: [{ name: "CUSTOM_TOKEN" }],
    });

    expect(payload.agent).toMatchObject({
      kind: "Agent",
      system_prompt_filename: "system_prompt_planning.j2",
      system_prompt_kwargs: {
        plan_structure: expect.stringContaining("OBJECTIVE"),
      },
      llm: {
        model: "openhands/minimax-m2.7",
        api_key: "gAAAAAencrypted-llm-api-key",
      },
      tools: [
        { name: "glob", params: {} },
        { name: "grep", params: {} },
        {
          name: "planning_file_editor",
          params: {
            plan_path: "/workspace/project/agent-canvas/.agents_tmp/PLAN.md",
          },
        },
      ],
      // Matches the SDK planning preset's get_planning_condenser.
      condenser: {
        kind: "LLMSummarizingCondenser",
        max_size: 100,
        keep_first: 6,
        llm: {
          model: "openhands/minimax-m2.7",
          usage_id: "planning_condenser",
        },
      },
    });
    expect(payload.agent_settings).toBeUndefined();
    expect(payload.worktree).toBe(false);
    expect(payload.tags).toEqual({ plannerparent: "parent-1" });
    expect(payload.secrets_encrypted).toBe(true);
    expect(payload.secrets).toHaveProperty("CUSTOM_TOKEN");
  });

  // @spec LLD-001 β€” Frontend always sends its chosen default model
  it.each([
    [
      "configured",
      { model: "anthropic/claude-opus-4-5" },
      "anthropic/claude-opus-4-5",
    ],
    ["undefined", {}, DEFAULT_SETTINGS.llm_model],
    ["an empty string", { model: "" }, DEFAULT_SETTINGS.llm_model],
    ["whitespace only", { model: "   " }, DEFAULT_SETTINGS.llm_model],
  ])(
    "sends the planner an explicit model when it is %s",
    (_case, llm, model) => {
      const payload = buildStartPlanningConversationRequest({
        encryptedAgentSettings: { llm },
        workingDir: "/workspace/project/agent-canvas",
        parentConversationId: "parent-1",
      });

      expect(payload.agent.llm).toMatchObject({ model });
    },
  );

  it("sends the planner the default model when settings carry no LLM", () => {
    const payload = buildStartPlanningConversationRequest({
      encryptedAgentSettings: {},
      workingDir: "/workspace/project/agent-canvas",
      parentConversationId: "parent-1",
    });

    expect(payload.agent.llm).toMatchObject({
      model: DEFAULT_SETTINGS.llm_model,
    });
  });

  it("links the local planner to its parent server-side so the relationship survives storage loss", () => {
    const payload = buildStartPlanningConversationRequest({
      encryptedAgentSettings: {
        agent_kind: "openhands",
        llm: { model: "openhands/minimax-m2.7" },
      },
      workingDir: "/workspace/project",
      parentConversationId: "parent-1",
    });

    // The agent-server derives the parent's `sub_conversation_ids` from this,
    // which is what makes the planner recoverable without localStorage.
    expect(payload.parent_conversation_id).toBe("parent-1");
  });

  it("requests DockerExecutionWorkspace for the planner on Docker execution servers", () => {
    const payload = buildStartPlanningConversationRequest({
      encryptedAgentSettings: {
        agent_kind: "openhands",
        llm: { model: "openhands/minimax-m2.7" },
      },
      workingDir: "/workspace",
      parentConversationId: "parent-1",
      executionRuntime: "docker",
    });

    expect(payload.workspace).toEqual({
      kind: "DockerExecutionWorkspace",
      working_dir: "/workspace",
    });
  });

  it("defaults the planner to LocalWorkspace when executionRuntime is not docker", () => {
    const payload = buildStartPlanningConversationRequest({
      encryptedAgentSettings: {
        agent_kind: "openhands",
        llm: { model: "openhands/minimax-m2.7" },
      },
      workingDir: "/host/workspace/project",
      parentConversationId: "parent-1",
    });

    expect(payload.workspace).toEqual({
      kind: "LocalWorkspace",
      working_dir: "/host/workspace/project",
    });
  });

  it("defaults the planner's max_iterations to 500 when not provided", () => {
    const payload = buildStartPlanningConversationRequest({
      encryptedAgentSettings: {
        agent_kind: "openhands",
        llm: { model: "openhands/minimax-m2.7" },
      },
      workingDir: "/workspace/project",
      parentConversationId: "parent-1",
    });

    expect(payload.max_iterations).toBe(500);
  });

  it("uses the caller-provided max_iterations instead of the hardcoded default", () => {
    const payload = buildStartPlanningConversationRequest({
      encryptedAgentSettings: {
        agent_kind: "openhands",
        llm: { model: "openhands/minimax-m2.7" },
      },
      workingDir: "/workspace/project",
      parentConversationId: "parent-1",
      maxIterations: 250,
    });

    expect(payload.max_iterations).toBe(250);
  });

  it("omits local planner helper conversations from paginated conversation results", () => {
    const page = toConversationPage({
      items: [
        {
          id: "main-1",
          created_at: "2024-01-01T00:00:00.000Z",
          updated_at: "2024-01-01T00:00:00.000Z",
          execution_status: "idle",
          tags: {},
        },
        {
          id: "plan-1",
          created_at: "2024-01-01T00:00:00.000Z",
          updated_at: "2024-01-01T00:00:00.000Z",
          execution_status: "idle",
          tags: { plannerparent: "main-1" },
        },
      ],
    });

    expect(page.items.map((item) => item.id)).toEqual(["main-1"]);
  });

  it("loads a catalog skill the opening slash command invokes", () => {
    // An automation card fills the chat input with the skill's own command
    // (`findAutomationCommand`), and most of the catalog's slash commands
    // belong to skills a profile does not select β€” without this the card
    // would silently do nothing.
    const payload = buildStartConversationRequest({
      settings: makeSettings({ agent_kind: "openhands" }),
      agentProfileId: "profile-xyz",
      agentProfileKind: "openhands",
      query: "/standup-digest:setup",
    });

    expect(
      payload.agent_launch_additions?.skills?.map((skill) => skill.name),
    ).toEqual(["slack-standup-digest"]);
  });
  it("does not admit a skill named mid-sentence rather than invoked", () => {
    const payload = buildStartConversationRequest({
      settings: makeSettings({ agent_kind: "openhands" }),
      agentProfileId: "profile-xyz",
      agentProfileKind: "openhands",
      query: "tell me what /standup-digest:setup would do",
    });

    expect(payload.agent_launch_additions).toBeUndefined();
  });
});

describe("buildStartConversationRequest β€” execution runtime", () => {
  it("requests DockerExecutionWorkspace from Docker execution servers", () => {
    const payload = buildStartConversationRequest({
      settings: makeSettings({ agent_kind: "openhands" }),
      agentProfileId: "profile-xyz",
      workingDir: "/host/workspace",
      executionRuntime: "docker",
    });

    expect(payload.workspace).toEqual({
      kind: "DockerExecutionWorkspace",
      working_dir: "/workspace",
    });
    expect(payload.worktree).toBe(false);
  });

  it("keeps LocalWorkspace for local and older servers", () => {
    const payload = buildStartConversationRequest({
      settings: makeSettings({ agent_kind: "openhands" }),
      agentProfileId: "profile-xyz",
      workingDir: "/host/workspace",
    });

    expect(payload.workspace).toEqual({
      kind: "LocalWorkspace",
      working_dir: "/host/workspace",
    });
  });
});

describe("buildStartPlanningConversationRequestWithEncryptedSettings", () => {
  const globallyActiveSettings = {
    agentSettings: {
      agent_kind: "openhands",
      llm: {
        model: "openhands/globally-active-model",
        api_key: "gAAAAAglobal-key",
        base_url: "https://global.example.com",
      },
    },
    conversationSettings: {},
    secretsEncrypted: true,
    skillEnablement: { disabledSkills: [] },
  };

  beforeEach(() => {
    vi.clearAllMocks();
    vi.mocked(SettingsService.getSettingsForConversation).mockResolvedValue(
      globallyActiveSettings,
    );
    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
      profiles: [
        {
          id: "profile-parent",
          name: "parent-profile",
          agent_kind: "openhands",
          revision: 1,
          llm_profile_ref: "parent-llm",
          mcp_server_refs: null,
        },
      ],
      active_agent_profile_id: "profile-other",
    });
    vi.mocked(ProfilesService.getProfile).mockResolvedValue({
      name: "parent-llm",
      api_key_set: true,
      config: {
        model: "openhands/parent-profile-model",
        api_key: "gAAAAAparent-key",
        base_url: "https://parent.example.com",
      },
    });
  });

  it("pins the planner to the parent's launched profile, not the globally active one", async () => {
    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace/project",
        parentConversationId: "parent-1",
        parentAgentProfileId: "profile-parent",
      });

    expect(ProfilesService.getProfile).toHaveBeenCalledWith(
      "parent-llm",
      "encrypted",
    );
    expect(payload.agent.llm).toMatchObject({
      model: "openhands/parent-profile-model",
      api_key: "gAAAAAparent-key",
      base_url: "https://parent.example.com",
    });
  });

  it("falls back to global settings when the parent was not launched from a profile", async () => {
    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace/project",
        parentConversationId: "parent-1",
        parentAgentProfileId: null,
      });

    expect(ProfilesService.getProfile).not.toHaveBeenCalled();
    expect(payload.agent.llm).toMatchObject({
      model: "openhands/globally-active-model",
    });
  });

  it("prefers the parent conversation's current active_profile over its launched agent profile", async () => {
    // The conversation launched under "parent-profile" (-> "parent-llm"), but
    // was later switched to a different LLM profile via /model or the
    // agent's own SwitchLLMTool β€” active_profile tracks that switch.
    vi.mocked(ProfilesService.getProfile).mockImplementation(async (name) =>
      name === "switched-llm"
        ? {
            name: "switched-llm",
            api_key_set: true,
            config: {
              model: "openhands/switched-model",
              api_key: "gAAAAAswitched-key",
              base_url: "https://switched.example.com",
            },
          }
        : {
            name: "parent-llm",
            api_key_set: true,
            config: {
              model: "openhands/parent-profile-model",
              api_key: "gAAAAAparent-key",
              base_url: "https://parent.example.com",
            },
          },
    );

    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace/project",
        parentConversationId: "parent-1",
        parentActiveProfileName: "switched-llm",
        parentAgentProfileId: "profile-parent",
      });

    expect(ProfilesService.getProfile).toHaveBeenCalledWith(
      "switched-llm",
      "encrypted",
    );
    // The launched agent profile must not even be consulted once
    // active_profile resolves successfully.
    expect(ProfilesService.getProfile).toHaveBeenCalledTimes(1);
    expect(payload.agent.llm).toMatchObject({
      model: "openhands/switched-model",
      api_key: "gAAAAAswitched-key",
      base_url: "https://switched.example.com",
    });
  });

  it("falls back to the launched agent profile when active_profile can't be resolved", async () => {
    vi.mocked(ProfilesService.getProfile).mockImplementation(async (name) => {
      if (name === "dangling-llm") throw new Error("not found");
      return {
        name: "parent-llm",
        api_key_set: true,
        config: {
          model: "openhands/parent-profile-model",
          api_key: "gAAAAAparent-key",
          base_url: "https://parent.example.com",
        },
      };
    });

    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace/project",
        parentConversationId: "parent-1",
        parentActiveProfileName: "dangling-llm",
        parentAgentProfileId: "profile-parent",
      });

    expect(payload.agent.llm).toMatchObject({
      model: "openhands/parent-profile-model",
    });
  });

  it("falls back to global settings when the parent's profile reference dangles", async () => {
    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
      profiles: [],
      active_agent_profile_id: null,
    });

    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace/project",
        parentConversationId: "parent-1",
        parentAgentProfileId: "profile-parent",
      });

    expect(ProfilesService.getProfile).not.toHaveBeenCalled();
    expect(payload.agent.llm).toMatchObject({
      model: "openhands/globally-active-model",
    });
  });

  it("mirrors the parent's configured max_iterations instead of hardcoding a lower cap", async () => {
    vi.mocked(SettingsService.getSettingsForConversation).mockResolvedValue({
      ...globallyActiveSettings,
      conversationSettings: { max_iterations: 1000 },
    });

    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace/project",
        parentConversationId: "parent-1",
      });

    expect(payload.max_iterations).toBe(1000);
  });

  it("falls back to 500 when the parent has no configured max_iterations", async () => {
    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace/project",
        parentConversationId: "parent-1",
      });

    expect(payload.max_iterations).toBe(500);
  });

  it("applies the full skill enablement to the planner's agent context, mirroring the code agent", async () => {
    // Both lists, because they cover different populations (#16302): the
    // allow-list gates the bundled catalog, the deny-list still wins over it.
    // `add-javadoc` is a catalog skill outside the recommended defaults, so
    // it only loads because the allow-list names it.
    vi.mocked(SettingsService.getSettingsForConversation).mockResolvedValue({
      ...globallyActiveSettings,
      skillEnablement: {
        enabledSkills: ["add-javadoc", "agent-memory"],
        disabledSkills: ["agent-memory"],
      },
    });

    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace/project",
        parentConversationId: "parent-1",
      });

    const skillNames = getPlannerAgentContextSkillNames(payload);
    expect(skillNames).not.toContain("agent-memory");
    expect(skillNames).toContain("add-javadoc");
  });

  it("gives the planner the parent profile's skill selection over the global lists", async () => {
    vi.mocked(SettingsService.getSettingsForConversation).mockResolvedValue({
      ...globallyActiveSettings,
      skillEnablement: { enabledSkills: ["agent-memory"], disabledSkills: [] },
    });
    vi.mocked(AgentProfilesService.getProfile).mockResolvedValue({
      name: "parent-profile",
      profile: {
        id: "profile-parent",
        name: "parent-profile",
        revision: 1,
        agent_kind: "openhands",
        llm_profile_ref: "parent-llm",
        public_skills: ["add-javadoc"],
        disabled_skills: [],
      },
    } as never);

    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace/project",
        parentConversationId: "parent-1",
        parentAgentProfileId: "profile-parent",
      });

    const skillNames = getPlannerAgentContextSkillNames(payload);
    expect(skillNames).toContain("add-javadoc");
    expect(skillNames).not.toContain("agent-memory");
  });

  it("threads executionRuntime through to DockerExecutionWorkspace selection", async () => {
    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/workspace",
        parentConversationId: "parent-1",
        executionRuntime: "docker",
      });

    expect(payload.workspace).toEqual({
      kind: "DockerExecutionWorkspace",
      working_dir: "/workspace",
    });
  });

  it("defaults to LocalWorkspace when executionRuntime is not provided", async () => {
    const payload =
      await buildStartPlanningConversationRequestWithEncryptedSettings({
        workingDir: "/host/workspace/project",
        parentConversationId: "parent-1",
      });

    expect(payload.workspace).toEqual({
      kind: "LocalWorkspace",
      working_dir: "/host/workspace/project",
    });
  });
});

describe("buildStartConversationRequest β€” agentProfileId path", () => {
  it("sends agent_profile_id and omits agent_settings (mutually exclusive)", () => {
    const settings = makeSettings({
      agent_kind: "openhands",
      llm: { model: "litellm_proxy/openai/gpt-5.5", api_key: "sk-test" },
    });

    const payload = buildStartConversationRequest({
      settings,
      agentProfileId: "profile-xyz",
      agentProfileKind: "openhands",
    });

    expect(payload.agent_profile_id).toBe("profile-xyz");
    expect(payload.agent_settings).toBeUndefined();
    expect(payload.agent_launch_additions).toBeUndefined();
    expect(payload.client_tools.map((tool) => tool.name)).toEqual([
      CANVAS_UI_CLIENT_TOOL_NAME,
      LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
      REQUEST_SECRET_TOOL_NAME,
    ]);
  });

  it("carries a per-launch LLM override", () => {
    const payload = buildStartConversationRequest({
      settings: makeSettings({ agent_kind: "openhands" }),
      agentProfileId: "profile-xyz",
      agentProfileKind: "openhands",
      llmProfileOverride: "fast",
    });

    expect(payload.agent_launch_additions).toEqual({
      llm_profile_ref: "fast",
    });
  });
  it("stamps the launched ACP profile's server as the ACP server tag", () => {
    const tagsFor = (
      agentProfileKind: "acp" | "openhands",
      acpServer?: string,
    ) =>
      buildStartConversationRequest({
        // Global settings name another ACP server; the profile decides.
        settings: makeSettings({ agent_kind: "acp", acp_server: "codex" }),
        agentProfileId: "profile-xyz",
        agentProfileKind,
        acpServer,
      }).tags;

    expect(tagsFor("acp", "claude-code")).toEqual({
      [ACP_SERVER_TAG_KEY]: "claude-code",
      [CLIENT_SOURCE_TAG_KEY]: AGENT_CANVAS_SOURCE,
    });
    expect(tagsFor("openhands")).toEqual({
      [CLIENT_SOURCE_TAG_KEY]: AGENT_CANVAS_SOURCE,
    });
  });
});