Skip to content

πŸ™Œ OpenHands: AI-Driven Development

45.9 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { MockInstance } 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 { AUTOMATION_FORM_UPDATE_TOOL_NAME } from "#/constants/automation-form";

import {
  ACP_SERVER_TAG_KEY,
  AGENT_CANVAS_SOURCE,
  CLIENT_SOURCE_TAG_KEY,
  WORKSPACE_TAG_KEY,
  buildWorkspaceTags,
  buildRuntimeServicesSystemSuffix,
  buildStartConversationRequest,
  buildStartConversationRequestWithEncryptedSettings,
  fetchBackendExecutionRuntime,
  getDefaultConversationTitle,
  parseRuntimeServicesInfo,
  toAppConversation,
  toHooksResponse,
  type DirectConversationInfo,
} from "#/api/agent-server-adapter";
import SettingsService from "#/api/settings-service/settings-service.api";
import { SecretsService } from "#/api/secrets-service";
import {
  removeStoredConversationMetadata,
  setStoredConversationMetadata,
} from "#/api/conversation-metadata-store";
import { HookType } from "@openhands/typescript-client";
import { SKILLS_CATALOG } from "@openhands/extensions/skills";
import type { HookConfig } from "@openhands/typescript-client";
import { DEFAULT_SETTINGS } from "#/services/settings";
import type { SettingsValue } from "#/types/settings";

const {
  mockGetAgentServerWorkingDir,
  mockGetEffectiveLocalBackend,
  mockGetCachedAgentServerInfo,
  mockGetServerInfo,
  mockGetActiveBackend,
  mockLoadHooks,
} = vi.hoisted(() => ({
  mockGetAgentServerWorkingDir: vi.fn(() => "/workspace/project/agent-canvas"),
  mockGetEffectiveLocalBackend: vi.fn(() => ({
    id: "default-local",
    name: "Local backend",
    host: "http://127.0.0.1:8000",
    apiKey: "session-key",
    kind: "local" as const,
  })),
  mockGetCachedAgentServerInfo: vi.fn<() => unknown>(() => null),
  mockGetServerInfo: vi.fn(),
  mockGetActiveBackend: vi.fn(() => ({
    backend: {
      id: "default-local",
      name: "Local backend",
      host: "http://127.0.0.1:8000",
      apiKey: "session-key",
      kind: "local" as const,
    },
  })),
  mockLoadHooks: vi.fn(),
}));

vi.mock("@openhands/typescript-client/clients", () => ({
  ServerClient: vi.fn(function ServerClientMock() {
    return {
      getServerInfo: mockGetServerInfo,
    };
  }),
  HooksClient: vi.fn(function HooksClientMock() {
    return { loadHooks: mockLoadHooks };
  }),
}));

vi.mock("#/api/agent-server-config", () => ({
  getAgentServerBaseUrl: vi.fn(() => "http://127.0.0.1:8000"),
  getAgentServerSessionApiKey: vi.fn(() => null),
  getAgentServerWorkingDir: mockGetAgentServerWorkingDir,
  shouldLoadPublicSkills: vi.fn(() => true),
  syncBakedSessionApiKey: vi.fn(),
}));

vi.mock("#/api/agent-server-compatibility", () => ({
  getCachedAgentServerInfo: mockGetCachedAgentServerInfo,
}));

vi.mock("#/api/backend-registry/active-store", () => ({
  getEffectiveLocalBackend: mockGetEffectiveLocalBackend,
  getActiveBackend: mockGetActiveBackend,
  isNoBackend: (backend: { id: string }) => backend.id === "no-backend",
}));

// `HookConfig` requires every event key, so build fixtures from a complete base.
const makeHookConfig = (overrides: Partial<HookConfig> = {}): HookConfig => ({
  pre_tool_use: [],
  post_tool_use: [],
  user_prompt_submit: [],
  session_start: [],
  session_end: [],
  stop: [],
  ...overrides,
});

const WORKSPACE_HOOK_CONFIG = makeHookConfig({
  session_start: [
    {
      matcher: "*",
      hooks: [{ command: "cat AGENTS.md", type: HookType.COMMAND }],
    },
  ],
});

const EXPLICIT_HOOK_CONFIG = makeHookConfig({
  session_start: [
    {
      matcher: "*",
      hooks: [{ command: "echo explicit", type: HookType.COMMAND }],
    },
  ],
});

beforeEach(() => {
  mockGetCachedAgentServerInfo.mockReturnValue(null);
  mockGetServerInfo.mockReset();
  mockGetEffectiveLocalBackend.mockReturnValue({
    id: "default-local",
    name: "Local backend",
    host: "http://127.0.0.1:8000",
    apiKey: "session-key",
    kind: "local",
  });
});

const PROFILE = {
  agentProfileId: "profile-1",
  agentProfileKind: "openhands" as const,
};

describe("buildStartConversationRequest", () => {
  it.each([{ city: "Tokyo" }, { metric: false }, { days: 0 }])(
    "rejects unsupported plugin parameters instead of silently stripping %o",
    (parameters) => {
      expect(() =>
        buildStartConversationRequest({
          ...PROFILE,
          settings: DEFAULT_SETTINGS,
          plugins: [{ source: "local-plugin", parameters }],
        }),
      ).toThrow();
    },
  );

  it.each(
    [5, 0, true, false, "", "Tokyo", [], [false]].map((parameters) => ({
      parameters,
    })),
  )(
    "rejects malformed plugin parameters instead of silently stripping $parameters",
    ({ parameters }) => {
      // Launch links can carry JSON values outside PluginSpec's static type.
      const plugins = JSON.parse(
        JSON.stringify([{ source: "local-plugin", parameters }]),
      );
      expect(() =>
        buildStartConversationRequest({
          ...PROFILE,
          settings: DEFAULT_SETTINGS,
          plugins,
        }),
      ).toThrow();
    },
  );

  it.each([undefined, null, {}])(
    "keeps coordinate-only plugins when parameters are %o",
    (parameters) => {
      const payload = buildStartConversationRequest({
        ...PROFILE,
        settings: DEFAULT_SETTINGS,
        plugins: [
          {
            source: "local-plugin",
            ref: "main",
            repo_path: "plugin",
            parameters,
          },
        ],
      });
      expect(payload.plugins).toEqual([
        { source: "local-plugin", ref: "main", repo_path: "plugin" },
      ]);
    },
  );

  it("includes the resolved title LLM profile when configured", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: DEFAULT_SETTINGS,
      titleLlmProfile: "Titles",
    });

    expect(payload.title_llm_profile).toBe("Titles");
  });

  it("omits the title LLM profile in automatic mode without a default", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: DEFAULT_SETTINGS,
    });

    expect(payload).not.toHaveProperty("title_llm_profile");
  });

  it("derives confirmation and security settings the same way as OpenHands", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: {
        ...DEFAULT_SETTINGS,
        agent_settings: {
          ...DEFAULT_SETTINGS.agent_settings,
          llm: { model: "nested-model" },
        },
        conversation_settings: {
          ...DEFAULT_SETTINGS.conversation_settings,
          confirmation_mode: true,
          security_analyzer: "llm",
        },
      },
    }) as {
      confirmation_policy: Record<string, unknown>;
      security_analyzer: Record<string, unknown>;
    };

    expect(payload.confirmation_policy).toEqual({
      kind: "ConfirmRisky",
      threshold: "HIGH",
      confirm_unknown: true,
    });
    expect(payload.security_analyzer).toEqual({
      kind: "LLMSecurityAnalyzer",
    });
  });

  it("uses the supplied conversationId and workingDir overrides", () => {
    const conversationId = "11111111-1111-4111-8111-111111111111";
    const workingDir = `/base/${conversationId}`;
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: {
        ...DEFAULT_SETTINGS,
        agent_settings: {
          ...DEFAULT_SETTINGS.agent_settings,
          llm: { model: "nested-model" },
        },
      },
      conversationId,
      workingDir,
    }) as {
      conversation_id?: string;
      workspace: { working_dir: string };
    };

    expect(payload.conversation_id).toBe(conversationId);
    expect(payload.workspace.working_dir).toBe(workingDir);
  });

  it("requests a git worktree for new conversations by default", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: {
        ...DEFAULT_SETTINGS,
        agent_settings: {
          ...DEFAULT_SETTINGS.agent_settings,
          llm: { model: "nested-model" },
        },
      },
    }) as { worktree: boolean };

    expect(payload.worktree).toBe(true);
  });

  it("can start a conversation without requesting a git worktree", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: {
        ...DEFAULT_SETTINGS,
        agent_settings: {
          ...DEFAULT_SETTINGS.agent_settings,
          llm: { model: "nested-model" },
        },
      },
      workingDir: "/Users/devin/project-without-git",
      worktree: false,
    }) as { worktree: boolean; workspace: { working_dir: string } };

    expect(payload.worktree).toBe(false);
    expect(payload.workspace.working_dir).toBe(
      "/Users/devin/project-without-git",
    );
  });

  it("forwards supported conversation runtime fields from nested settings", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: {
        ...DEFAULT_SETTINGS,
        agent_settings: {
          ...DEFAULT_SETTINGS.agent_settings,
          llm: { model: "nested-model" },
        },
        conversation_settings: {
          ...DEFAULT_SETTINGS.conversation_settings,
          hook_config: { on_start: [] },
          tool_module_qualnames: { demo_tool: "pkg.tools.demo" },
          agent_definitions: [
            { name: "reviewer", system_prompt: "be helpful" },
          ],
        },
      },
      conversationInstructions: "Follow the repo conventions.",
      plugins: [
        { source: "github.com/org/plugin", ref: "main", repo_path: "/" },
      ],
    }) as Record<string, unknown>;

    expect(payload.hook_config).toEqual({ on_start: [] });
    expect(payload.tool_module_qualnames).toEqual({
      demo_tool: "pkg.tools.demo",
    });
    expect(payload.agent_definitions).toEqual([
      { name: "reviewer", system_prompt: "be helpful" },
    ]);
    expect(payload.plugins).toEqual([
      { source: "github.com/org/plugin", ref: "main", repo_path: "/" },
    ]);
    expect(payload.initial_message).toEqual({
      role: "user",
      content: [{ type: "text", text: "Follow the repo conventions." }],
      run: true,
    });
  });

  it("uses workspaceHookConfig when conversation_settings.hook_config is omitted", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: DEFAULT_SETTINGS,
      workspaceHookConfig: WORKSPACE_HOOK_CONFIG,
    }) as Record<string, unknown>;

    expect(payload.hook_config).toEqual(WORKSPACE_HOOK_CONFIG);
  });

  it("prioritizes conversation_settings.hook_config over workspaceHookConfig", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: {
        ...DEFAULT_SETTINGS,
        conversation_settings: {
          ...DEFAULT_SETTINGS.conversation_settings,
          hook_config: EXPLICIT_HOOK_CONFIG as unknown as SettingsValue,
        },
      },
      workspaceHookConfig: WORKSPACE_HOOK_CONFIG,
    }) as Record<string, unknown>;

    expect(payload.hook_config).toEqual(EXPLICIT_HOOK_CONFIG);
  });

  it("serializes custom secrets as host-relative LookupSecret entries", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: {
        ...DEFAULT_SETTINGS,
        agent_settings: {
          ...DEFAULT_SETTINGS.agent_settings,
          llm: { model: "nested-model" },
        },
      },
      customSecrets: [
        { name: "API_KEY", description: "Primary API key" },
        { name: "folder/name", description: "Nested secret" },
      ],
    }) as {
      secrets: Record<
        string,
        {
          kind: string;
          url: string;
          description?: string;
          headers?: Record<string, string>;
        }
      >;
    };

    expect(payload.secrets).toEqual({
      API_KEY: {
        kind: "LookupSecret",
        url: "/api/settings/secrets/API_KEY",
        description: "Primary API key",
        headers: { "X-Session-API-Key": "session-key" },
      },
      "folder/name": {
        kind: "LookupSecret",
        url: "/api/settings/secrets/folder%2Fname",
        description: "Nested secret",
        headers: { "X-Session-API-Key": "session-key" },
      },
    });
  });

  describe("secret delivery", () => {
    it("delivers provider credentials and user secrets as LookupSecrets for an ACP profile", () => {
      // Provider credentials (e.g. a saved CODEX_AUTH_JSON) ride as
      // LookupSecrets like any custom secret; the server keeps only the ones
      // the profile's `secret_refs` allows.
      const payload = buildStartConversationRequest({
        settings: DEFAULT_SETTINGS,
        agentProfileId: "profile-acp",
        agentProfileKind: "acp",
        customSecrets: [{ name: "CODEX_AUTH_JSON" }, { name: "MY_TOKEN" }],
      }) as unknown as { secrets: Record<string, { kind: string }> };

      expect(payload.secrets.CODEX_AUTH_JSON?.kind).toBe("LookupSecret");
      expect(payload.secrets.MY_TOKEN?.kind).toBe("LookupSecret");
    });

    it("never asks the server to decrypt request secrets", () => {
      const payload = buildStartConversationRequest({
        ...PROFILE,
        settings: DEFAULT_SETTINGS,
        customSecrets: [{ name: "MY_TOKEN" }],
      });

      expect(payload).not.toHaveProperty("secrets_encrypted");
      expect(payload).not.toHaveProperty("agent_settings");
    });
  });

  describe("client tool injection", () => {
    it("sends canvas_ui as a client-defined JSON tool", () => {
      const payload = buildStartConversationRequest({
        ...PROFILE,
        settings: DEFAULT_SETTINGS,
      });

      expect(payload.client_tools[0]).toMatchObject({
        name: CANVAS_UI_CLIENT_TOOL_NAME,
        parameters: {
          type: "object",
          properties: {
            command: {
              enum: ["navigate_to_file", "open_tab", "show_preview"],
            },
          },
          required: ["command"],
        },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: false,
        },
      });
      expect(payload.tool_module_qualnames).toBeUndefined();
    });

    it("omits the client tool for an ACP profile when global settings are stale", () => {
      const payload = buildStartConversationRequest({
        settings: DEFAULT_SETTINGS,
        agentProfileId: "profile-acp",
        agentProfileKind: "acp",
      });

      expect(payload.client_tools).toEqual([]);
    });

    it("sends the client tool for an OpenHands profile", () => {
      const payload = buildStartConversationRequest({
        settings: DEFAULT_SETTINGS,
        agentProfileId: "profile-openhands",
        agentProfileKind: "openhands",
      });

      expect(payload.client_tools.map((tool) => tool.name)).toEqual([
        CANVAS_UI_CLIENT_TOOL_NAME,
        LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
        REQUEST_SECRET_TOOL_NAME,
      ]);
    });

    it("adds automation setup tags to local conversation requests", () => {
      const payload = buildStartConversationRequest({
        ...PROFILE,
        settings: DEFAULT_SETTINGS,
        automationSetup: true,
        automationSetupTags: {
          automationdraftid: "draft-1",
          automationmaterializeddraftid: "auto-1",
        },
      });

      expect(payload.tags).toEqual(
        expect.objectContaining({
          automationsetup: "draft",
          automationdraftid: "draft-1",
          automationmaterializeddraftid: "auto-1",
          clientsource: "agentcanvas",
        }),
      );
    });

    it.each([
      {
        automationSetup: false,
        expectedTools: [
          CANVAS_UI_CLIENT_TOOL_NAME,
          LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
          REQUEST_SECRET_TOOL_NAME,
        ],
      },
      {
        automationSetup: true,
        expectedTools: [
          CANVAS_UI_CLIENT_TOOL_NAME,
          LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
          REQUEST_SECRET_TOOL_NAME,
          AUTOMATION_FORM_UPDATE_TOOL_NAME,
        ],
      },
    ])(
      "builds client tools for automationSetup=$automationSetup",
      ({ automationSetup, expectedTools }) => {
        const payload = buildStartConversationRequest({
          ...PROFILE,
          settings: DEFAULT_SETTINGS,
          automationSetup,
        });

        expect(payload.client_tools.map((tool) => tool.name)).toEqual(
          expectedTools,
        );
      },
    );

    it("sends the client tool when resuming a conversation", () => {
      const payload = buildStartConversationRequest({
        ...PROFILE,
        settings: DEFAULT_SETTINGS,
        conversationId: "legacy-conversation-id",
      }) as { conversation_id: string; client_tools: Array<{ name: string }> };

      expect(payload.conversation_id).toBe("legacy-conversation-id");
      expect(payload.client_tools.map((tool) => tool.name)).toEqual([
        CANVAS_UI_CLIENT_TOOL_NAME,
        LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
        REQUEST_SECRET_TOOL_NAME,
      ]);
    });

    it("drops conflicting user-supplied Canvas module qualnames", () => {
      const payload = buildStartConversationRequest({
        ...PROFILE,
        settings: {
          ...DEFAULT_SETTINGS,
          conversation_settings: {
            ...DEFAULT_SETTINGS.conversation_settings,
            tool_module_qualnames: {
              canvas_ui: "custom_canvas_ui_tool",
              [CANVAS_UI_CLIENT_TOOL_NAME]: "custom_canvas_ui_control_tool",
              my_tool: "my_package.my_tool",
            },
          },
        },
      }) as { tool_module_qualnames: Record<string, string> };

      expect(payload.tool_module_qualnames).toEqual({
        my_tool: "my_package.my_tool",
      });
    });

    it("preserves non-Canvas custom tool modules", () => {
      const payload = buildStartConversationRequest({
        ...PROFILE,
        settings: {
          ...DEFAULT_SETTINGS,
          conversation_settings: {
            ...DEFAULT_SETTINGS.conversation_settings,
            tool_module_qualnames: { my_tool: "my_package.my_tool" },
          },
        },
      }) as { tool_module_qualnames: Record<string, string> };

      expect(payload.tool_module_qualnames).toEqual({
        my_tool: "my_package.my_tool",
      });
    });
  });
});

describe("getDefaultConversationTitle", () => {
  it("formats the title using the first 5 characters of the conversation id", () => {
    expect(getDefaultConversationTitle("372eb-1234-5678-9abc")).toBe(
      "Conversation 372eb",
    );
  });
});

describe("buildWorkspaceTags (#17386)", () => {
  it("emits the workspace tag with a normalized path", () => {
    expect(buildWorkspaceTags("/Users/jane/projects/openhands/")).toEqual({
      [WORKSPACE_TAG_KEY]: "/Users/jane/projects/openhands",
    });
  });

  it("returns an empty object for null/empty/whitespace input", () => {
    expect(buildWorkspaceTags(null)).toEqual({});
    expect(buildWorkspaceTags(undefined)).toEqual({});
    expect(buildWorkspaceTags("   ")).toEqual({});
  });

  it("only ever emits keys the agent-server accepts (`^[a-z0-9]+$`)", () => {
    const tags = buildWorkspaceTags("/Users/jane/projects/openhands");
    for (const key of Object.keys(tags)) {
      expect(key).toMatch(/^[a-z0-9]+$/);
    }
  });
});

describe("toAppConversation", () => {
  const baseInfo: DirectConversationInfo = {
    id: "372eb-1234-5678-9abc",
    created_at: "2026-01-01T00:00:00Z",
    updated_at: "2026-01-01T00:00:00Z",
  };

  describe("server-side workspace tag fallback (#17386)", () => {
    afterEach(() => {
      removeStoredConversationMetadata(baseInfo.id);
    });

    it("uses a key the agent-server will accept (lowercase alphanumeric)", () => {
      // The agent-server rejects tag keys that are not `^[a-z0-9]+$` (SDK
      // conversation/types.py), which would 422 the create request.
      expect(WORKSPACE_TAG_KEY).toMatch(/^[a-z0-9]+$/);
    });

    it("hydrates selected_workspace from the tag when localStorage has none", () => {
      const result = toAppConversation({
        ...baseInfo,
        tags: { [WORKSPACE_TAG_KEY]: "/Users/jane/projects/openhands" },
      });

      expect(result.selected_workspace).toBe("/Users/jane/projects/openhands");
    });

    it("prefers stored metadata over the tag (warm cache for the creating client)", () => {
      setStoredConversationMetadata(baseInfo.id, {
        selected_repository: null,
        selected_branch: null,
        git_provider: null,
        selected_workspace: "/Users/jane/projects/local-fork",
      });

      const result = toAppConversation({
        ...baseInfo,
        tags: { [WORKSPACE_TAG_KEY]: "/Users/jane/projects/openhands" },
      });

      expect(result.selected_workspace).toBe("/Users/jane/projects/local-fork");
    });

    it("stays null when neither localStorage nor the tag has a workspace", () => {
      const result = toAppConversation({ ...baseInfo, tags: {} });

      expect(result.selected_workspace).toBeNull();
    });
  });

  it("uses the archived status for a missing runtime that cannot resume", () => {
    const result = toAppConversation({
      ...baseInfo,
      runtime_info: {
        runtime_status: "missing",
        can_resume: false,
      },
    });

    expect(result.sandbox_status).toBe("MISSING");
  });

  it("does not archive a missing runtime that can resume", () => {
    const result = toAppConversation({
      ...baseInfo,
      runtime_info: {
        runtime_status: "missing",
        can_resume: true,
      },
    });

    expect(result.sandbox_status).toBeNull();
  });

  it("combines stats.usage_to_metrics into metrics when the backend doesn't set metrics directly (#16480)", () => {
    const result = toAppConversation({
      ...baseInfo,
      stats: {
        usage_to_metrics: {
          agent: {
            model_name: "agent-model",
            accumulated_cost: 1.5,
            max_budget_per_task: 10,
            accumulated_token_usage: {
              prompt_tokens: 100,
              completion_tokens: 20,
              cache_read_tokens: 5,
              cache_write_tokens: 1,
              context_window: 8000,
              per_turn_token: 120,
            },
            costs: [],
            response_latencies: [],
            token_usages: [],
          },
          condenser: {
            model_name: "condenser-model",
            accumulated_cost: 0.5,
            max_budget_per_task: null,
            accumulated_token_usage: {
              prompt_tokens: 40,
              completion_tokens: 10,
              cache_read_tokens: 0,
              cache_write_tokens: 0,
              context_window: 4000,
              per_turn_token: 50,
            },
            costs: [],
            response_latencies: [],
            token_usages: [],
          },
        },
      },
    });

    expect(result.metrics).toEqual({
      accumulated_cost: 2,
      max_budget_per_task: 10,
      accumulated_token_usage: {
        prompt_tokens: 140,
        completion_tokens: 30,
        cache_read_tokens: 5,
        cache_write_tokens: 1,
        context_window: 8000,
        per_turn_token: 120,
      },
    });
  });

  it("prefers backend-provided metrics over stats.usage_to_metrics when both are present", () => {
    const result = toAppConversation({
      ...baseInfo,
      metrics: { accumulated_cost: 3, max_budget_per_task: null },
      stats: {
        usage_to_metrics: {
          agent: {
            model_name: "agent-model",
            accumulated_cost: 999,
            max_budget_per_task: null,
            accumulated_token_usage: null,
            costs: [],
            response_latencies: [],
            token_usages: [],
          },
        },
      },
    });

    expect(result.metrics?.accumulated_cost).toBe(3);
  });

  it("defaults metrics to a zero-cost snapshot when neither metrics nor stats are present", () => {
    const result = toAppConversation({ ...baseInfo });

    expect(result.metrics).toEqual({
      accumulated_cost: 0,
      max_budget_per_task: null,
      accumulated_token_usage: null,
    });
  });

  it("falls back to the default title when the backend returns null", () => {
    const result = toAppConversation({ ...baseInfo, title: null });
    expect(result.title).toBe("Conversation 372eb");
  });

  it("falls back to the default title when the backend returns undefined", () => {
    const result = toAppConversation({ ...baseInfo });
    expect(result.title).toBe("Conversation 372eb");
  });

  it("falls back to the default title when the backend returns an empty string", () => {
    const result = toAppConversation({ ...baseInfo, title: "" });
    expect(result.title).toBe("Conversation 372eb");
  });

  it("falls back to the default title when the backend returns whitespace only", () => {
    const result = toAppConversation({ ...baseInfo, title: "   " });
    expect(result.title).toBe("Conversation 372eb");
  });

  it("preserves a backend-provided title when one is set", () => {
    const result = toAppConversation({
      ...baseInfo,
      title: "My real title",
    });
    expect(result.title).toBe("My real title");
  });

  it("hydrates selected_workspace from stored metadata so the sidebar can group by it", () => {
    setStoredConversationMetadata(baseInfo.id, {
      selected_repository: null,
      selected_branch: null,
      git_provider: null,
      selected_workspace: "/workspace/agent-server-gui",
    });
    try {
      const result = toAppConversation({
        ...baseInfo,
        workspace: { working_dir: "/workspace/agent-server-gui/wt-abc" },
      });
      expect(result.selected_workspace).toBe("/workspace/agent-server-gui");
    } finally {
      removeStoredConversationMetadata(baseInfo.id);
    }
  });

  it("hydrates active_profile from stored metadata so the switcher shows the exact profile (#1082)", () => {
    setStoredConversationMetadata(baseInfo.id, {
      selected_repository: null,
      selected_branch: null,
      git_provider: null,
      active_profile: "claude-sonnet-4.6",
    });
    try {
      const result = toAppConversation({
        ...baseInfo,
        agent: {
          kind: "Agent",
          llm: { model: "openhands/claude-sonnet-4-6" },
        },
      });
      expect(result.active_profile).toBe("claude-sonnet-4.6");
    } finally {
      removeStoredConversationMetadata(baseInfo.id);
    }
  });

  it("marks openhands conversations and surfaces the agent.llm.model", () => {
    const result = toAppConversation({
      ...baseInfo,
      agent: { kind: "Agent", llm: { model: "claude-sonnet-4-6" } },
    });
    expect(result.agent_kind).toBe("openhands");
    expect(result.llm_model).toBe("claude-sonnet-4-6");
  });

  it("marks ACP conversations and surfaces the configured acp_model", () => {
    // The SDK's ACPAgent may still carry a sentinel ``llm`` (``acp-managed``)
    // for cost-attribution. Consumers should see the concrete ACP model Canvas
    // configured, while SwitchProfileButton remains gated by agent_kind.
    const result = toAppConversation({
      ...baseInfo,
      agent: {
        kind: "ACPAgent",
        acp_model: "claude-sonnet-4-6",
        llm: { model: "acp-managed" },
      },
    });
    expect(result.agent_kind).toBe("acp");
    expect(result.llm_model).toBe("claude-sonnet-4-6");
  });

  it("prefers ACP runtime model fields over configured acp_model", () => {
    const result = toAppConversation({
      ...baseInfo,
      current_model_id: "claude-sonnet-4-6",
      current_model_name: "Claude Sonnet",
      agent: {
        kind: "ACPAgent",
        acp_model: "claude-opus-4-7",
        llm: { model: "acp-managed" },
      },
    });
    expect(result.agent_kind).toBe("acp");
    expect(result.llm_model).toBe("Claude Sonnet");
  });

  it("surfaces the runtime ACP default model over a configured acp_model", () => {
    // claude-agent-acp 0.44+ exposes ``default`` ("Default (recommended)")
    // as a real, selectable model in its configOptions select. The runtime
    // ``current_model_*`` fields take precedence over the configured
    // ``acp_model``, so a session actually running on ``default`` must
    // surface that on the chip instead of the stale configured value.
    const result = toAppConversation({
      ...baseInfo,
      current_model_id: "default",
      current_model_name: "Default (recommended)",
      agent: {
        kind: "ACPAgent",
        acp_model: "claude-sonnet-4-6",
        llm: { model: "acp-managed" },
      },
    });
    expect(result.agent_kind).toBe("acp");
    expect(result.llm_model).toBe("Default (recommended)");
  });

  it("falls back to a non-sentinel ACP llm.model for SDKs that mirror acp_model there", () => {
    const result = toAppConversation({
      ...baseInfo,
      agent: { kind: "ACPAgent", llm: { model: "claude-sonnet-4-6" } },
    });
    expect(result.agent_kind).toBe("acp");
    expect(result.llm_model).toBe("claude-sonnet-4-6");
  });

  it("surfaces ACP default model surfaced via the configured acp_model", () => {
    // ``default`` / ``Default (recommended)`` is a real claude-agent-acp
    // model id (not an SDK placeholder), so it must surface like any other
    // configured model.
    const result = toAppConversation({
      ...baseInfo,
      agent: {
        kind: "ACPAgent",
        acp_model: "Default (recommended)",
        llm: { model: "acp-managed" },
      },
    });
    expect(result.agent_kind).toBe("acp");
    expect(result.llm_model).toBe("Default (recommended)");
  });

  it("surfaces ACP default model surfaced via agent.llm.model", () => {
    // Same as above, one rung lower in the precedence chain: ``default`` is
    // a real model id and should surface as-is.
    const result = toAppConversation({
      ...baseInfo,
      agent: { kind: "ACPAgent", llm: { model: "default" } },
    });
    expect(result.agent_kind).toBe("acp");
    expect(result.llm_model).toBe("default");
  });

  it("surfaces acp_server from tags.acpserver for ACP conversations", () => {
    // The ``acpserver`` conversation tag is stamped at create time
    // (``buildStartConversationRequest``) but never previously plumbed
    // through on read β€” the sidebar chip in agent-canvas#405 needs this
    // value to resolve the human display name ("Claude Code" / "Codex" /
    // "Gemini CLI").
    const result = toAppConversation({
      ...baseInfo,
      agent: { kind: "ACPAgent", llm: { model: "acp-managed" } },
      tags: { [ACP_SERVER_TAG_KEY]: "claude-code" },
    });
    expect(result.acp_server).toBe("claude-code");
  });

  it("leaves acp_server null when an ACP conversation has no tag stamped", () => {
    // Older conversations created before the tag was added, or ACP
    // conversations created via the raw API, won't have the tag. The
    // sidebar should still render a chip ("ACP") β€” but the resolver gets
    // null here and the UI fallback handles the generic label.
    const result = toAppConversation({
      ...baseInfo,
      agent: { kind: "ACPAgent", llm: { model: "acp-managed" } },
    });
    expect(result.agent_kind).toBe("acp");
    expect(result.acp_server).toBeNull();
  });

  it("ignores tags.acpserver on OpenHands conversations to prevent stray-tag bleed", () => {
    // The agent-server's pydantic model doesn't enforce that ``acpserver``
    // is only stamped on ACP conversations. Defensively gating on
    // ``agent.kind === "ACPAgent"`` keeps a misconfigured tag from
    // turning the sidebar of an OpenHands conversation into "Claude
    // Code". Pairs with the ``llm_model`` null-out for ACP.
    const result = toAppConversation({
      ...baseInfo,
      agent: { kind: "Agent", llm: { model: "claude-sonnet-4-6" } },
      tags: { [ACP_SERVER_TAG_KEY]: "claude-code" },
    });
    expect(result.agent_kind).toBe("openhands");
    expect(result.acp_server).toBeNull();
  });
});

describe("buildRuntimeServicesSystemSuffix", () => {
  it("returns undefined when runtime services info is absent", () => {
    expect(buildRuntimeServicesSystemSuffix()).toBeUndefined();
  });

  it("parses runtime services JSON strings", () => {
    expect(
      parseRuntimeServicesInfo(
        JSON.stringify({
          mode: "dev:automation",
          services: {
            agent_server: { url_from_agent: "http://localhost:18000" },
          },
        }),
      )?.mode,
    ).toBe("dev:automation");
  });

  it("returns null when runtime services JSON is malformed", () => {
    expect(parseRuntimeServicesInfo("{not valid json")).toBeNull();
  });

  it("returns undefined when the JSON has no services", () => {
    expect(buildRuntimeServicesSystemSuffix({ mode: "x" })).toBeUndefined();
  });

  it("renders a <RUNTIME_SERVICES> block when an automation entry is present", () => {
    const suffix = buildRuntimeServicesSystemSuffix({
      mode: "dev:automation",
      agent_host_alias: "localhost",
      services: {
        agent_server: {
          description: "self",
          url_from_agent: "http://localhost:18000",
        },
        automation: {
          description: "automations",
          url_from_agent: "http://localhost:18001",
          api_prefix: "/api/automation",
          docs_url: "http://localhost:18001/api/automation/docs",
          openapi_url: "http://localhost:18001/api/automation/openapi.json",
          auth_env_var: "OPENHANDS_AUTOMATION_API_KEY",
        },
      },
    });
    expect(suffix).toBeDefined();
    expect(suffix).toContain("<RUNTIME_SERVICES>");
    expect(suffix).toContain("dev:automation");
    expect(suffix).toContain("http://localhost:18000");
    expect(suffix).toContain("http://localhost:18001");
    expect(suffix).toContain("http://localhost:18001/api/automation/docs");
    expect(suffix).toContain(
      "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY",
    );
    expect(suffix).not.toContain("X-API-Key: $OPENHANDS_AUTOMATION_API_KEY");
    expect(suffix).toContain("</RUNTIME_SERVICES>");
    // The "don't guess" line should reference the actual agent-server URL
    // for this stack, not a hardcoded port. The assertion anchors on the URL
    // we supplied above.
    expect(suffix).toContain(
      "In particular, http://localhost:18000 inside your sandbox is the Agent Server",
    );
  });

  it("uses the configured agent-server URL in the don't-guess line (not a hardcoded :8000)", () => {
    // dev:safe runs the agent-server on :18000, not :8000. Make sure the
    // rendered block doesn't lie to the agent about its own URL.
    const suffix = buildRuntimeServicesSystemSuffix({
      mode: "dev:safe",
      services: {
        agent_server: { url_from_agent: "http://localhost:18000" },
      },
    });
    expect(suffix).toBeDefined();
    expect(suffix).toContain(
      "In particular, http://localhost:18000 inside your sandbox is the Agent Server",
    );
    expect(suffix).not.toContain(
      "In particular, http://localhost:8000 inside your sandbox",
    );
  });

  it("renders the frontend entry with the new key", () => {
    const suffix = buildRuntimeServicesSystemSuffix({
      mode: "dev:static",
      services: {
        agent_server: { url_from_agent: "http://localhost:18000" },
        frontend: {
          kind: "static",
          description: "Static-file server hosting the agent-canvas build.",
          url_from_agent: "http://localhost:3001",
        },
      },
    });
    expect(suffix).toContain("* Frontend: http://localhost:3001");
    expect(suffix).toContain("Static-file server");
    // Should NOT mislabel a static-build frontend as "Vite frontend".
    expect(suffix).not.toContain("Vite frontend");
  });

  it("explicitly mentions when automation is absent", () => {
    const suffix = buildRuntimeServicesSystemSuffix({
      mode: "dev:safe",
      services: {
        agent_server: { url_from_agent: "http://localhost:18000" },
      },
    });
    expect(suffix).toBeDefined();
    expect(suffix).toContain("Automation backend: not running");
  });

  it("reads server_info from the cached probe when available", async () => {
    mockGetCachedAgentServerInfo.mockReturnValue({
      version: "1.48.0",
      execution_runtime: "docker",
    });

    const runtime = await fetchBackendExecutionRuntime();

    expect(runtime).toBe("docker");
    expect(mockGetServerInfo).not.toHaveBeenCalled();
  });

  it("fetches /server_info when there is no cached probe", async () => {
    mockGetServerInfo.mockResolvedValue({
      version: "1.48.0",
      execution_runtime: "local",
    });

    const runtime = await fetchBackendExecutionRuntime();

    expect(runtime).toBe("local");
    expect(mockGetServerInfo).toHaveBeenCalledOnce();
  });
});

type LaunchAdditions = {
  system_message_suffix_append?: string;
  llm_profile_ref?: string;
  skills?: Array<{ name: string; source: string; content: string }>;
};

const additionsOf = (payload: unknown): LaunchAdditions | undefined =>
  (payload as { agent_launch_additions?: LaunchAdditions })
    .agent_launch_additions;

const RUNTIME_SERVICES = {
  mode: "dev:automation",
  services: {
    agent_server: { url_from_agent: "http://localhost:18000" },
    automation: { url_from_agent: "http://localhost:18001" },
  },
};

describe("profile launch additions", () => {
  it("carries runtime services and leaves the saved global suffix to the profile", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: {
        ...DEFAULT_SETTINGS,
        agent_settings: {
          ...DEFAULT_SETTINGS.agent_settings,
          agent_context: { system_message_suffix: "MARKER-GLOBAL-RULES" },
        },
      },
      query: "hello",
      runtimeServicesInfo: RUNTIME_SERVICES,
    });

    const appended = additionsOf(payload)?.system_message_suffix_append;
    expect(payload.agent_profile_id).toBe("profile-1");
    expect(payload).not.toHaveProperty("agent_settings");
    expect(appended).toMatch(/^<RUNTIME_SERVICES>/);
    expect(appended).toContain("http://localhost:18001");
    expect(appended).not.toContain("MARKER-GLOBAL-RULES");
  });

  it("carries runtime services on an ACP profile launch too", () => {
    const payload = buildStartConversationRequest({
      settings: DEFAULT_SETTINGS,
      query: "hello",
      agentProfileId: "profile-acp",
      agentProfileKind: "acp",
      runtimeServicesInfo: RUNTIME_SERVICES,
    });

    expect(payload.agent_profile_id).toBe("profile-acp");
    expect(additionsOf(payload)?.system_message_suffix_append).toContain(
      "<RUNTIME_SERVICES>",
    );
  });

  it.each([
    ["the toggle is on and the profile carries a router", true, true, true],
    ["the profile carries no router", true, false, false],
    ["the toggle is off", false, true, false],
  ])(
    "routes the first message only when %s",
    (_case, runAtStart, profileHasRouter, expected) => {
      const payload = buildStartConversationRequest({
        ...PROFILE,
        settings: {
          ...DEFAULT_SETTINGS,
          run_router_at_conversation_start: runAtStart,
        },
        profileHasRouter,
        query: "hello",
      });

      const appended = additionsOf(payload)?.system_message_suffix_append;
      if (expected) {
        expect(appended).toContain("<ROUTE_AT_CONVERSATION_START>");
      } else {
        expect(appended ?? "").not.toContain("ROUTE_AT_CONVERSATION_START");
      }
    },
  );

  it("adds a catalog skill the opening message invokes", () => {
    const [entry] = SKILLS_CATALOG;
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: DEFAULT_SETTINGS,
      query: `/${entry.name} please`,
    });

    const skills = additionsOf(payload)?.skills ?? [];
    expect(skills.map((skill) => skill.name)).toEqual([entry.name]);
    expect(skills[0].content).toBe(entry.content);
    expect(skills[0].source).toMatch(new RegExp(`/${entry.name}/SKILL\\.md$`));
  });

  it.each([
    ["an ACP profile", "acp" as const, (name: string) => `/${name} please`],
    [
      "a message that invokes no catalog skill",
      "openhands" as const,
      () => "/not-a-catalog-skill please",
    ],
  ])("adds no skills for %s", (_case, kind, query) => {
    const payload = buildStartConversationRequest({
      settings: DEFAULT_SETTINGS,
      agentProfileId: "profile-1",
      agentProfileKind: kind,
      query: query(SKILLS_CATALOG[0].name),
    });

    expect(additionsOf(payload)?.skills).toBeUndefined();
  });

  it("omits additions when there is nothing to add", () => {
    const payload = buildStartConversationRequest({
      ...PROFILE,
      settings: DEFAULT_SETTINGS,
      query: "hello",
    });

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

describe("buildStartConversationRequestWithEncryptedSettings", () => {
  let settingsSpy: MockInstance;
  let secretsSpy: MockInstance;

  beforeEach(() => {
    mockLoadHooks.mockReset();
    // Stub only the collaborators; the hooks lookup is what's under test.
    settingsSpy = vi
      .spyOn(SettingsService, "getSettingsForConversation")
      .mockResolvedValue({
        agentSettings: (DEFAULT_SETTINGS.agent_settings ?? {}) as Record<
          string,
          SettingsValue
        >,
        conversationSettings: (DEFAULT_SETTINGS.conversation_settings ??
          {}) as Record<string, SettingsValue>,
        secretsEncrypted: true,
        skillEnablement: { disabledSkills: [] },
      });
    secretsSpy = vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([]);
  });

  // vitest is not configured with `restoreMocks`, so restore explicitly.
  afterEach(() => {
    settingsSpy.mockRestore();
    secretsSpy.mockRestore();
  });

  it("looks hooks up in hooksProjectDir, not the conversation working dir", async () => {
    mockLoadHooks.mockResolvedValue({ hook_config: WORKSPACE_HOOK_CONFIG });

    const payload = await buildStartConversationRequestWithEncryptedSettings({
      ...PROFILE,
      settings: DEFAULT_SETTINGS,
      workingDir: "/workspace/my-project/0f1e2d3c",
      hooksProjectDir: "/workspace/my-project",
    });

    expect(mockLoadHooks).toHaveBeenCalledWith({
      project_dir: "/workspace/my-project",
    });
    expect(payload.hook_config).toEqual(WORKSPACE_HOOK_CONFIG);
  });

  it("falls back to the configured working dir when no hooksProjectDir is given", async () => {
    mockLoadHooks.mockResolvedValue({ hook_config: null });

    await buildStartConversationRequestWithEncryptedSettings({
      ...PROFILE,
      settings: DEFAULT_SETTINGS,
      workingDir: "/workspace/my-project/0f1e2d3c",
    });

    expect(mockLoadHooks).toHaveBeenCalledWith({
      project_dir: "/workspace/project/agent-canvas",
    });
  });

  it("omits hook_config when the workspace has no hooks", async () => {
    mockLoadHooks.mockResolvedValue({ hook_config: null });

    const payload = await buildStartConversationRequestWithEncryptedSettings({
      ...PROFILE,
      settings: DEFAULT_SETTINGS,
      hooksProjectDir: "/workspace/my-project",
    });

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

  it("starts the conversation without hooks when the lookup fails", async () => {
    mockLoadHooks.mockRejectedValue(new Error("500 Internal Server Error"));

    const payload = await buildStartConversationRequestWithEncryptedSettings({
      ...PROFILE,
      settings: DEFAULT_SETTINGS,
      hooksProjectDir: "/workspace/my-project",
    });

    expect(payload.hook_config).toBeUndefined();
    expect(payload.agent_profile_id).toBe("profile-1");
  });

  it("routes the first message for a profile that carries a router", async () => {
    const payload = await buildStartConversationRequestWithEncryptedSettings({
      ...PROFILE,
      settings: {
        ...DEFAULT_SETTINGS,
        run_router_at_conversation_start: true,
      },
      profileHasRouter: true,
      hooksProjectDir: "/workspace/my-project",
    });

    expect(additionsOf(payload)?.system_message_suffix_append).toContain(
      "ROUTE_AT_CONVERSATION_START",
    );
  });
});

describe("toHooksResponse", () => {
  // Prompt and agent hooks reach Canvas over the wire with `prompt`/`system_prompt`,
  // which the typed client's `HookDefinition` does not declare yet.
  const wireHook = (hook: Record<string, unknown>) =>
    hook as unknown as HookConfig["stop"][number]["hooks"][number];

  it("carries a prompt hook's prompt through", () => {
    const response = toHooksResponse(
      makeHookConfig({
        stop: [
          {
            matcher: "*",
            hooks: [
              wireHook({
                type: "prompt",
                command: "",
                prompt: "QA_F07 prompt hook",
                system_prompt: null,
                timeout: 60,
                async: false,
              }),
            ],
          },
        ],
      }),
    );

    expect(response.hooks).toEqual([
      {
        event_type: "stop",
        matchers: [
          {
            matcher: "*",
            hooks: [
              {
                type: "prompt",
                command: "",
                prompt: "QA_F07 prompt hook",
                timeout: 60,
                async: false,
              },
            ],
          },
        ],
      },
    ]);
  });

  it("carries an agent hook's system_prompt through", () => {
    const response = toHooksResponse(
      makeHookConfig({
        session_start: [
          {
            matcher: "*",
            hooks: [
              wireHook({
                type: "agent",
                command: "",
                prompt: null,
                system_prompt: "QA_F07 agent hook",
                timeout: 60,
                async: false,
              }),
            ],
          },
        ],
      }),
    );

    expect(response.hooks).toEqual([
      {
        event_type: "session_start",
        matchers: [
          {
            matcher: "*",
            hooks: [
              {
                type: "agent",
                command: "",
                system_prompt: "QA_F07 agent hook",
                timeout: 60,
                async: false,
              },
            ],
          },
        ],
      },
    ]);
  });

  it("keeps command hooks unchanged", () => {
    const response = toHooksResponse(
      makeHookConfig({
        pre_tool_use: [
          {
            matcher: "terminal",
            hooks: [{ type: HookType.COMMAND, command: "true", timeout: 10 }],
          },
        ],
      }),
    );

    expect(response.hooks).toEqual([
      {
        event_type: "pre_tool_use",
        matchers: [
          {
            matcher: "terminal",
            hooks: [{ type: HookType.COMMAND, command: "true", timeout: 10 }],
          },
        ],
      },
    ]);
  });
});