π OpenHands: AI-Driven Development
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,
});
});
});