Skip to content

🙌 OpenHands: AI-Driven Development

feat: add Model Router "Run at conversation start" toggle (#17797)

Juan Pedro Michelini Jorged01cc2569e0b
diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.ts
index 4cb05ed830..3b279204ac 100644
--- a/__tests__/api/agent-server-adapter.test.ts
+++ b/__tests__/api/agent-server-adapter.test.ts
@@ -41,6 +41,7 @@ const {
mockGetServerInfo,
mockGetActiveBackend,
mockLoadHooks,
+ mockListMetaProfiles,
} = vi.hoisted(() => ({
mockGetAgentServerWorkingDir: vi.fn(() => "/workspace/project/agent-canvas"),
mockIsAgentServerToolAvailable: vi.fn((_toolName: string) => true),
@@ -63,6 +64,7 @@ const {
},
})),
mockLoadHooks: vi.fn(),
+ mockListMetaProfiles: vi.fn(),
}));
vi.mock("@openhands/typescript-client/clients", () => ({
@@ -74,6 +76,9 @@ vi.mock("@openhands/typescript-client/clients", () => ({
HooksClient: vi.fn(function HooksClientMock() {
return { loadHooks: mockLoadHooks };
}),
+ MetaProfilesClient: vi.fn(function MetaProfilesClientMock() {
+ return { listMetaProfiles: mockListMetaProfiles };
+ }),
}));
vi.mock("#/api/agent-server-config", () => ({
@@ -699,6 +704,77 @@ describe("buildStartConversationRequest", () => {
expect(payload.agent_settings.agent_context?.secrets).toBeUndefined();
});
+ it("appends the route-at-conversation-start suffix when the toggle is on and a meta-profile is active (OpenHands agent)", () => {
+ const payload = buildStartConversationRequest({
+ settings: {
+ ...DEFAULT_SETTINGS,
+ run_router_at_conversation_start: true,
+ },
+ hasActiveMetaProfile: true,
+ }) as {
+ agent_settings: { agent_context?: { system_message_suffix?: string } };
+ };
+
+ const suffix = payload.agent_settings.agent_context?.system_message_suffix;
+ expect(suffix).toContain("ROUTE_AT_CONVERSATION_START");
+ expect(suffix).toContain("route_task_to_model");
+ });
+
+ it("appends the route-at-conversation-start suffix for an inline ACP launch when the toggle is on and a meta-profile is active", () => {
+ const payload = buildStartConversationRequest({
+ settings: {
+ ...DEFAULT_SETTINGS,
+ agent_settings: {
+ ...DEFAULT_SETTINGS.agent_settings,
+ agent_kind: "acp",
+ acp_server: "claude-code",
+ acp_command: ["npx", "-y", "@agentclientprotocol/claude-agent-acp"],
+ },
+ run_router_at_conversation_start: true,
+ },
+ hasActiveMetaProfile: true,
+ }) as {
+ agent_settings: { agent_context?: { system_message_suffix?: string } };
+ };
+
+ expect(
+ payload.agent_settings.agent_context?.system_message_suffix,
+ ).toContain("ROUTE_AT_CONVERSATION_START");
+ });
+
+ it("does not add the router suffix when the toggle is on but no meta-profile is active", () => {
+ // With no active meta-profile the agent-server does not attach
+ // `route_task_to_model`, so the instruction must not be emitted even if
+ // the toggle was left on (e.g. the active profile was just deleted).
+ const payload = buildStartConversationRequest({
+ settings: {
+ ...DEFAULT_SETTINGS,
+ run_router_at_conversation_start: true,
+ },
+ hasActiveMetaProfile: false,
+ }) as {
+ agent_settings: { agent_context?: { system_message_suffix?: string } };
+ };
+
+ const suffix =
+ payload.agent_settings.agent_context?.system_message_suffix ?? "";
+ expect(suffix).not.toContain("ROUTE_AT_CONVERSATION_START");
+ });
+
+ it("does not add a system_message_suffix for the router when the toggle is off (default)", () => {
+ const payload = buildStartConversationRequest({
+ settings: DEFAULT_SETTINGS,
+ }) as {
+ agent_settings: { agent_context?: { system_message_suffix?: string } };
+ };
+
+ // The suffix may be undefined (no runtime-services block either); assert
+ // specifically that the router sentinel is absent when present.
+ const suffix =
+ payload.agent_settings.agent_context?.system_message_suffix ?? "";
+ expect(suffix).not.toContain("ROUTE_AT_CONVERSATION_START");
+ });
+
describe("ACP secret delivery", () => {
// Settings factory for a containerized ACP conversation.
const acpSettings = (overrides: Record<string, unknown> = {}) => ({
@@ -1890,6 +1966,12 @@ describe("buildStartConversationRequestWithEncryptedSettings", () => {
skillEnablement: { disabledSkills: [] },
});
secretsSpy = vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([]);
+ // Default: no active meta-profile so the route-at-start suffix is off.
+ mockListMetaProfiles.mockReset();
+ mockListMetaProfiles.mockResolvedValue({
+ meta_profiles: [],
+ active_meta_profile: null,
+ });
});
// vitest is not configured with `restoreMocks`, so restore explicitly.
@@ -1948,4 +2030,76 @@ describe("buildStartConversationRequestWithEncryptedSettings", () => {
expect(payload.hook_config).toBeUndefined();
expect(payload.agent_settings).toBeDefined();
});
+
+ it("stamps the route-at-start suffix when the toggle is on and a meta-profile is active", async () => {
+ mockListMetaProfiles.mockResolvedValue({
+ meta_profiles: [],
+ active_meta_profile: {
+ llm_router_profile_id: "router-1",
+ name: "Model Router",
+ routing_strategy: "classification",
+ routing_models: [],
+ router_model: null,
+ fallback_model: null,
+ },
+ });
+
+ const payload = (await buildStartConversationRequestWithEncryptedSettings({
+ settings: {
+ ...DEFAULT_SETTINGS,
+ run_router_at_conversation_start: true,
+ },
+ hooksProjectDir: "/workspace/my-project",
+ })) as {
+ agent_settings: {
+ agent_context?: { system_message_suffix?: string };
+ };
+ };
+
+ expect(
+ payload.agent_settings?.agent_context?.system_message_suffix,
+ ).toContain("ROUTE_AT_CONVERSATION_START");
+ });
+
+ it("omits the route-at-start suffix when the toggle is on but no meta-profile is active", async () => {
+ // active_meta_profile is null by default (see beforeEach). Even with the
+ // toggle on, no suffix should be emitted since the agent-server won't
+ // attach `route_task_to_model` without an active profile.
+ const payload = (await buildStartConversationRequestWithEncryptedSettings({
+ settings: {
+ ...DEFAULT_SETTINGS,
+ run_router_at_conversation_start: true,
+ },
+ hooksProjectDir: "/workspace/my-project",
+ })) as {
+ agent_settings: {
+ agent_context?: { system_message_suffix?: string };
+ };
+ };
+
+ expect(
+ payload.agent_settings?.agent_context?.system_message_suffix ?? "",
+ ).not.toContain("ROUTE_AT_CONVERSATION_START");
+ });
+
+ it("omits the route-at-start suffix when the meta-profiles endpoint fails (fails closed)", async () => {
+ mockListMetaProfiles.mockRejectedValue(new Error("503 Service Unavailable"));
+
+ const payload = (await buildStartConversationRequestWithEncryptedSettings({
+ settings: {
+ ...DEFAULT_SETTINGS,
+ run_router_at_conversation_start: true,
+ },
+ hooksProjectDir: "/workspace/my-project",
+ })) as {
+ agent_settings: {
+ agent_context?: { system_message_suffix?: string };
+ };
+ };
+
+ // If we can't confirm a router is active, fail closed: no instruction.
+ expect(
+ payload.agent_settings?.agent_context?.system_message_suffix ?? "",
+ ).not.toContain("ROUTE_AT_CONVERSATION_START");
+ });
});
diff --git a/__tests__/api/cloud/conversation-create.test.ts b/__tests__/api/cloud/conversation-create.test.ts
index a46e6b109e..e758a802dd 100644
--- a/__tests__/api/cloud/conversation-create.test.ts
+++ b/__tests__/api/cloud/conversation-create.test.ts
@@ -94,6 +94,93 @@ describe("AgentServerConversationService cloud branch", () => {
expect(result.app_conversation_id).toBeNull();
});
+ it("createConversation forwards the route-at-start suffix as agent_launch_additions on the cloud path", async () => {
+ fetchMock.mockResolvedValue(
+ mockJsonResponse({
+ id: "task-124",
+ created_by_user_id: null,
+ status: "WORKING",
+ detail: null,
+ app_conversation_id: null,
+ agent_server_url: null,
+ request: {},
+ created_at: "2026-05-06T00:00:00Z",
+ updated_at: "2026-05-06T00:00:00Z",
+ }),
+ );
+
+ await AgentServerConversationService.createConversation({
+ initialUserMsg: "fix the bug",
+ runRouterAtConversationStart: true,
+ hasActiveMetaProfile: true,
+ });
+
+ const [, init] = getFetchCall(fetchMock);
+ const requestBody = getJsonBody(init) as {
+ agent_launch_additions?: { system_message_suffix_append?: string };
+ };
+
+ expect(requestBody.agent_launch_additions).toBeDefined();
+ expect(
+ requestBody.agent_launch_additions?.system_message_suffix_append,
+ ).toContain("ROUTE_AT_CONVERSATION_START");
+ });
+
+ it("createConversation omits agent_launch_additions on the cloud path when the toggle is off", async () => {
+ fetchMock.mockResolvedValue(
+ mockJsonResponse({
+ id: "task-125",
+ created_by_user_id: null,
+ status: "WORKING",
+ detail: null,
+ app_conversation_id: null,
+ agent_server_url: null,
+ request: {},
+ created_at: "2026-05-06T00:00:00Z",
+ updated_at: "2026-05-06T00:00:00Z",
+ }),
+ );
+
+ await AgentServerConversationService.createConversation({
+ initialUserMsg: "fix the bug",
+ });
+
+ const [, init] = getFetchCall(fetchMock);
+ const requestBody = getJsonBody(init);
+
+ expect(requestBody).not.toHaveProperty("agent_launch_additions");
+ });
+
+ it("createConversation omits agent_launch_additions on the cloud path when no meta-profile is active", async () => {
+ // The toggle is on, but with no active meta-profile the agent-server
+ // does not attach `route_task_to_model`, so the instruction must not be
+ // emitted (the router would have nothing to call).
+ fetchMock.mockResolvedValue(
+ mockJsonResponse({
+ id: "task-126",
+ created_by_user_id: null,
+ status: "WORKING",
+ detail: null,
+ app_conversation_id: null,
+ agent_server_url: null,
+ request: {},
+ created_at: "2026-05-06T00:00:00Z",
+ updated_at: "2026-05-06T00:00:00Z",
+ }),
+ );
+
+ await AgentServerConversationService.createConversation({
+ initialUserMsg: "fix the bug",
+ runRouterAtConversationStart: true,
+ hasActiveMetaProfile: false,
+ });
+
+ const [, init] = getFetchCall(fetchMock);
+ const requestBody = getJsonBody(init);
+
+ expect(requestBody).not.toHaveProperty("agent_launch_additions");
+ });
+
it("getStartTask polls /api/v1/app-conversations/start-tasks?ids= directly", async () => {
fetchMock.mockResolvedValue(
mockJsonResponse([
diff --git a/__tests__/components/settings/meta-llm-profiles/meta-llm-settings-view.test.tsx b/__tests__/components/settings/meta-llm-profiles/meta-llm-settings-view.test.tsx
index 7403fa5d50..1fcc72cb9e 100644
--- a/__tests__/components/settings/meta-llm-profiles/meta-llm-settings-view.test.tsx
+++ b/__tests__/components/settings/meta-llm-profiles/meta-llm-settings-view.test.tsx
@@ -10,6 +10,8 @@ import * as useProviderConnectionsHook from "#/hooks/query/use-provider-connecti
import * as useSaveMetaProfileHook from "#/hooks/mutation/use-save-meta-profile";
import * as useActivateMetaProfileHook from "#/hooks/mutation/use-activate-meta-profile";
import * as useDeleteMetaProfileHook from "#/hooks/mutation/use-delete-meta-profile";
+import * as useSettingsHook from "#/hooks/query/use-settings";
+import * as useSaveSettingsHook from "#/hooks/mutation/use-save-settings";
import MetaProfilesService from "#/api/meta-profiles-service/meta-profiles-service.api";
import ProfilesService from "#/api/profiles-service/profiles-service.api";
import {
@@ -26,6 +28,8 @@ vi.mock("#/hooks/query/use-provider-connections");
vi.mock("#/hooks/mutation/use-save-meta-profile");
vi.mock("#/hooks/mutation/use-activate-meta-profile");
vi.mock("#/hooks/mutation/use-delete-meta-profile");
+vi.mock("#/hooks/query/use-settings");
+vi.mock("#/hooks/mutation/use-save-settings");
vi.mock("#/api/meta-profiles-service/meta-profiles-service.api");
vi.mock("#/api/profiles-service/profiles-service.api");
vi.mock("#/utils/custom-toast-handlers");
@@ -119,6 +123,14 @@ describe("MetaLlmSettingsView", () => {
vi.mocked(useDeleteMetaProfileHook.useDeleteMetaProfile).mockReturnValue(
mockMutation(vi.fn()),
);
+ vi.mocked(useSettingsHook.useSettings).mockReturnValue({
+ data: { run_router_at_conversation_start: false } as never,
+ isLoading: false,
+ error: null,
+ } as never);
+ vi.mocked(useSaveSettingsHook.useSaveSettings).mockReturnValue(
+ mockMutation(vi.fn()),
+ );
vi.mocked(ProfilesService.getProfile).mockResolvedValue({
name: "minimax",
api_key_set: true,
@@ -418,4 +430,100 @@ describe("MetaLlmSettingsView", () => {
expect(screen.getByTestId("meta-profile-set-active")).toBeDisabled();
});
+
+ it("renders the Run-at-conversation-start toggle disabled when no meta-profile is active", () => {
+ vi.mocked(useMetaProfilesHook.useMetaProfiles).mockReturnValue({
+ data: { meta_profiles: [], active_meta_profile: null },
+ isLoading: false,
+ error: null,
+ } as unknown as ReturnType<typeof useMetaProfilesHook.useMetaProfiles>);
+
+ renderWithProviders(<MetaLlmSettingsView />);
+
+ expect(
+ screen.getByTestId("meta-profile-run-at-conversation-start"),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByTestId("meta-profile-run-at-conversation-start-switch"),
+ ).toBeDisabled();
+ });
+
+ it("does not clear a saved on preference while the meta-profiles query is still loading", () => {
+ // Regression guard for the load-time effect that destroyed the toggle:
+ // ``useMetaProfiles`` returns ``active_meta_profile: null`` until the
+ // fetch resolves, so a mount-time guard must NOT fire saveSettings to
+ // clear a persisted ``true``. The launch paths gate on the active
+ // meta-profile instead, so the preference is preserved for when a router
+ // is active again.
+ const saveSettingsMock = vi.fn();
+ const base = mockMutation(vi.fn()) as Record<string, unknown>;
+ vi.mocked(useSaveSettingsHook.useSaveSettings).mockReturnValue({
+ ...base,
+ mutate: saveSettingsMock,
+ } as never);
+ vi.mocked(useMetaProfilesHook.useMetaProfiles).mockReturnValue({
+ // Loading: data not yet resolved, so active is null.
+ data: undefined,
+ isLoading: true,
+ error: null,
+ } as unknown as ReturnType<typeof useMetaProfilesHook.useMetaProfiles>);
+ vi.mocked(useSettingsHook.useSettings).mockReturnValue({
+ data: { run_router_at_conversation_start: true } as never,
+ isLoading: false,
+ error: null,
+ } as never);
+
+ renderWithProviders(<MetaLlmSettingsView />);
+
+ // The switch renders off (no active router) but the persisted preference
+ // is left intact — saveSettings must not be called to clear it.
+ expect(
+ screen.getByTestId("meta-profile-run-at-conversation-start-switch"),
+ ).not.toBeChecked();
+ expect(saveSettingsMock).not.toHaveBeenCalled();
+ });
+
+ it("persists the Run-at-conversation-start toggle through useSaveSettings", async () => {
+ const saveSettingsMock = vi.fn();
+ const base = mockMutation(vi.fn()) as Record<string, unknown>;
+ vi.mocked(useSaveSettingsHook.useSaveSettings).mockReturnValue({
+ ...base,
+ mutate: saveSettingsMock,
+ } as never);
+ vi.mocked(useSettingsHook.useSettings).mockReturnValue({
+ data: { run_router_at_conversation_start: false } as never,
+ isLoading: false,
+ error: null,
+ } as never);
+
+ renderWithProviders(<MetaLlmSettingsView />);
+
+ const user = userEvent.setup();
+ const toggle = screen.getByTestId(
+ "meta-profile-run-at-conversation-start-switch",
+ );
+ expect(toggle).not.toBeDisabled();
+ // An active meta-profile is set in the default beforeEach mock.
+ await user.click(toggle);
+
+ await waitFor(() =>
+ expect(saveSettingsMock).toHaveBeenCalledWith({
+ run_router_at_conversation_start: true,
+ }),
+ );
+ });
+
+ it("reflects the persisted Run-at-conversation-start value as on", () => {
+ vi.mocked(useSettingsHook.useSettings).mockReturnValue({
+ data: { run_router_at_conversation_start: true } as never,
+ isLoading: false,
+ error: null,
+ } as never);
+
+ renderWithProviders(<MetaLlmSettingsView />);
+
+ expect(
+ screen.getByTestId("meta-profile-run-at-conversation-start-switch"),
+ ).toBeChecked();
+ });
});
diff --git a/__tests__/services/child-conversation-launch.test.ts b/__tests__/services/child-conversation-launch.test.ts
index 3e4b52dc49..12bd247d2b 100644
--- a/__tests__/services/child-conversation-launch.test.ts
+++ b/__tests__/services/child-conversation-launch.test.ts
@@ -23,6 +23,8 @@ const {
mockGetCloudStartTask,
mockPickCloudBackend,
mockGetCachedAgentServerVersion,
+ mockGetSettings,
+ mockListMetaProfiles,
} = vi.hoisted(() => ({
mockCreateConversation: vi.fn(),
mockResolveWorkingDir: vi.fn(),
@@ -32,6 +34,8 @@ const {
mockGetCloudStartTask: vi.fn(),
mockPickCloudBackend: vi.fn(),
mockGetCachedAgentServerVersion: vi.fn(),
+ mockGetSettings: vi.fn(),
+ mockListMetaProfiles: vi.fn(),
}));
vi.mock(
@@ -70,6 +74,14 @@ vi.mock("#/utils/custom-toast-handlers", () => ({
displaySuccessToastWithLink: vi.fn(),
}));
+vi.mock("#/api/settings-service/settings-service.api", () => ({
+ default: { getSettings: mockGetSettings },
+}));
+
+vi.mock("#/api/meta-profiles-service/meta-profiles-service.api", () => ({
+ default: { listMetaProfiles: mockListMetaProfiles },
+}));
+
const PARENT_ID = "parent-conversation-id";
function action(
@@ -133,6 +145,13 @@ describe("handleLaunchChildConversationAction", () => {
mockUpdateTitle.mockResolvedValue(undefined);
mockSendMessage.mockResolvedValue(undefined);
mockGetCachedAgentServerVersion.mockReturnValue("1.37.1");
+ mockGetSettings.mockResolvedValue({
+ run_router_at_conversation_start: false,
+ });
+ mockListMetaProfiles.mockResolvedValue({
+ meta_profiles: [],
+ active_meta_profile: null,
+ });
});
describe("parameter validation", () => {
@@ -436,6 +455,58 @@ describe("handleLaunchChildConversationAction", () => {
);
});
+ it("skips the meta-profiles fetch and launch additions when the router toggle is off", async () => {
+ mockCreateCloudAppConversation.mockResolvedValue({
+ id: "start-task-id",
+ app_conversation_id: "cloud-child-id",
+ status: "READY",
+ });
+
+ await handleLaunchChildConversationAction(
+ action({ target: "cloud" }),
+ PARENT_ID,
+ nextToolCallId(),
+ );
+
+ expect(mockListMetaProfiles).not.toHaveBeenCalled();
+ const [request] = mockCreateCloudAppConversation.mock.calls.at(-1) as [
+ Record<string, unknown>,
+ ];
+ expect(request).not.toHaveProperty("agent_launch_additions");
+ });
+
+ it("stamps the router instruction when the toggle is on and a meta-profile is active", async () => {
+ mockGetSettings.mockResolvedValue({
+ run_router_at_conversation_start: true,
+ });
+ mockListMetaProfiles.mockResolvedValue({
+ meta_profiles: [{ name: "router" }],
+ active_meta_profile: "router",
+ });
+ mockCreateCloudAppConversation.mockResolvedValue({
+ id: "start-task-id",
+ app_conversation_id: "cloud-child-id",
+ status: "READY",
+ });
+
+ await handleLaunchChildConversationAction(
+ action({ target: "cloud" }),
+ PARENT_ID,
+ nextToolCallId(),
+ );
+
+ expect(mockCreateCloudAppConversation).toHaveBeenCalledWith(
+ expect.objectContaining({
+ agent_launch_additions: {
+ system_message_suffix_append: expect.stringContaining(
+ "route_task_to_model",
+ ),
+ },
+ }),
+ cloudBackend,
+ );
+ });
+
// Cloud provisions the sandbox asynchronously and only fills in
// `app_conversation_id` at READY, so reporting the first response would
// hand the agent a result with no conversation to open.
diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.ts
index aff94e4f67..b2bf6c8632 100644
--- a/src/api/agent-server-adapter.ts
+++ b/src/api/agent-server-adapter.ts
@@ -38,6 +38,7 @@ import {
type SkillEnablement,
} from "#/utils/skill-enablement";
import SettingsService from "./settings-service/settings-service.api";
+import MetaProfilesService from "./meta-profiles-service/meta-profiles-service.api";
import { getStoredConversationMetadata } from "./conversation-metadata-store";
import LLMSubscriptionService from "./llm-subscription-service";
import {
@@ -349,6 +350,42 @@ export function buildRuntimeServicesSystemSuffix(
return lines.join("\n");
}
+/**
+ * System-message instruction appended when the user enables "Run on first
+ * message" for the Model Router. With an active meta-profile the
+ * agent-server attaches the ``route_task_to_model`` tool; this suffix tells
+ * the agent to call it with the *first* user message before doing anything
+ * else, so the opening request is always routed to the classifier-selected
+ * model. Subsequent messages are left to the agent's own judgment.
+ *
+ * Only emitted when ``runAtStart`` is on AND a meta-profile is active
+ * (``hasActiveRouter``): with no active meta-profile the agent-server does
+ * not attach ``route_task_to_model``, so emitting the instruction would tell
+ * the agent to call a tool it does not have. Gating here — inside the single
+ * suffix builder that every launch path funnels through — keeps behavior
+ * consistent regardless of how the toggle was persisted, so a stale ``true``
+ * (e.g. the active profile was just deleted) can never reach the prompt.
+ *
+ * Returns `undefined` when disabled so no prompt noise is added — the default
+ * "everything works as normal" path is byte-identical to before.
+ */
+export function buildRouterAtStartSystemSuffix(
+ runAtStart: boolean,
+ hasActiveRouter: boolean,
+): string | undefined {
+ if (!runAtStart || !hasActiveRouter) return undefined;
+ return [
+ "<ROUTE_AT_CONVERSATION_START>",
+ "Before responding to the FIRST user message of this conversation, call",
+ "the `route_task_to_model` tool with that user message so the active",
+ "Model Router selects the appropriate model. After the router switches",
+ "the model, continue handling the user's request with the switched",
+ "model. Apply this only to the very first user message; do not route",
+ "subsequent messages this way.",
+ "</ROUTE_AT_CONVERSATION_START>",
+ ].join("\n");
+}
+
export function toConversationUrl(conversationId: string): string {
// Local-format conversation URL — points at whichever local agent-server
// is actually serving the conversation (the bundled one when the active
@@ -859,9 +896,15 @@ function buildAgentContext(
runtimeServicesInfo?: RuntimeServicesInfo | null,
enablement: SkillEnablement = {},
invokedCatalogSkill?: string,
+ runRouterAtStart?: boolean,
+ hasActiveRouter?: boolean,
): SettingsRecord {
const runtimeServicesSuffix =
buildRuntimeServicesSystemSuffix(runtimeServicesInfo);
+ const routerAtStartSuffix = buildRouterAtStartSystemSuffix(
+ runRouterAtStart ?? false,
+ hasActiveRouter ?? false,
+ );
const existingContext = toRecord(agentSettings.agent_context);
// Merge bundled public skills with any skills already present in the
@@ -909,8 +952,12 @@ function buildAgentContext(
// prompt too. The allow-list has no counterpart to send: the backend
// loads no catalog skills of its own (`load_public_skills` is false).
disabled_skills: disabledSkills,
- ...(runtimeServicesSuffix
- ? { system_message_suffix: runtimeServicesSuffix }
+ ...(runtimeServicesSuffix || routerAtStartSuffix
+ ? {
+ system_message_suffix: [runtimeServicesSuffix, routerAtStartSuffix]
+ .filter((s): s is string => Boolean(s))
+ .join("\n\n"),
+ }
: {}),
};
}
@@ -946,6 +993,7 @@ function buildConfiguredAcpAgentSettings(
settings: Settings,
runtimeServicesInfo?: RuntimeServicesInfo | null,
query?: string,
+ hasActiveMetaProfile?: boolean,
): AgentSettingsPayload {
const agentSettings = toRecord(settings.agent_settings);
const payload: AgentSettingsPayload = {
@@ -955,6 +1003,8 @@ function buildConfiguredAcpAgentSettings(
runtimeServicesInfo,
toSkillEnablement(settings),
findInvokedCatalogSkill(query),
+ settings.run_router_at_conversation_start,
+ hasActiveMetaProfile,
),
};
@@ -1014,6 +1064,7 @@ function buildConfiguredOpenHandsAgentSettings(
settings: Settings,
runtimeServicesInfo?: RuntimeServicesInfo | null,
query?: string,
+ hasActiveMetaProfile?: boolean,
): AgentSettingsPayload {
const agentSettings = toRecord(settings.agent_settings);
const llm = buildNormalizedLlmSettings(agentSettings.llm);
@@ -1044,6 +1095,8 @@ function buildConfiguredOpenHandsAgentSettings(
runtimeServicesInfo,
toSkillEnablement(settings),
findInvokedCatalogSkill(query),
+ settings.run_router_at_conversation_start,
+ hasActiveMetaProfile,
),
tools: getAgentTools(agentSettings),
};
@@ -1053,13 +1106,20 @@ function buildConfiguredAgentSettings(
settings: Settings,
runtimeServicesInfo?: RuntimeServicesInfo | null,
query?: string,
+ hasActiveMetaProfile?: boolean,
): AgentSettingsPayload {
return isAcpAgent(settings)
- ? buildConfiguredAcpAgentSettings(settings, runtimeServicesInfo, query)
+ ? buildConfiguredAcpAgentSettings(
+ settings,
+ runtimeServicesInfo,
+ query,
+ hasActiveMetaProfile,
+ )
: buildConfiguredOpenHandsAgentSettings(
settings,
runtimeServicesInfo,
query,
+ hasActiveMetaProfile,
);
}
@@ -1185,6 +1245,16 @@ export interface StartConversationOptions {
runtimeServicesInfo?: RuntimeServicesInfo | null;
executionRuntime?: AgentServerInfo["execution_runtime"];
workspaceHookConfig?: HookConfig | null;
+ /**
+ * Whether a Model Router meta-profile is currently active. The
+ * route-at-conversation-start system-message suffix is only emitted when
+ * this is true AND ``settings.run_router_at_conversation_start`` is on —
+ * without an active meta-profile the agent-server does not attach the
+ * ``route_task_to_model`` tool, so the instruction would be a no-op (or
+ * worse, tell the agent to call a tool it lacks). Defaults to false so a
+ * sync caller that omits it never emits the suffix.
+ */
+ hasActiveMetaProfile?: boolean;
}
/**
@@ -1236,6 +1306,7 @@ export function buildStartConversationRequest(
sourceAgentSettings,
options.runtimeServicesInfo,
options.query,
+ options.hasActiveMetaProfile,
);
const acpServerTag = acpMode
? getAcpServerTag(sourceAgentSettings)
@@ -1663,15 +1734,23 @@ export async function buildStartConversationRequestWithEncryptedSettings(options
import("./hooks-service"),
]);
- const [settingsResult, customSecrets, serverInfo, workspaceHookConfig] =
- await Promise.all([
- SettingsService.getSettingsForConversation(),
- SecretsService.getSecrets(),
- fetchBackendServerInfo(),
- options.hooksProjectDir === null
- ? Promise.resolve(null)
- : HooksService.loadWorkspaceHooks(options.hooksProjectDir),
- ]);
+ const [
+ settingsResult,
+ customSecrets,
+ serverInfo,
+ workspaceHookConfig,
+ metaProfiles,
+ ] = await Promise.all([
+ SettingsService.getSettingsForConversation(),
+ SecretsService.getSecrets(),
+ fetchBackendServerInfo(),
+ options.hooksProjectDir === null
+ ? Promise.resolve(null)
+ : HooksService.loadWorkspaceHooks(options.hooksProjectDir),
+ // Best-effort: if the meta-profiles endpoint is unreachable we cannot
+ // confirm a router is active, so fail closed (no route-at-start suffix).
+ MetaProfilesService.listMetaProfiles().catch(() => null),
+ ]);
const { agentSettings, conversationSettings, secretsEncrypted } =
settingsResult;
@@ -1679,6 +1758,7 @@ export async function buildStartConversationRequestWithEncryptedSettings(options
(serverInfo as { runtime_services?: unknown } | null)?.runtime_services,
);
const executionRuntime = serverInfo?.execution_runtime;
+ const hasActiveMetaProfile = !!metaProfiles?.active_meta_profile;
// A profile launch resolves the LLM server-side, so the current-settings
// subscription check doesn't apply (and can't see the profile's LLM).
@@ -1695,6 +1775,7 @@ export async function buildStartConversationRequestWithEncryptedSettings(options
runtimeServicesInfo,
executionRuntime,
workspaceHookConfig,
+ hasActiveMetaProfile,
});
}
diff --git a/src/api/conversation-service/agent-server-conversation-service.api.ts b/src/api/conversation-service/agent-server-conversation-service.api.ts
index ed3ede82d4..a53dc1729e 100644
--- a/src/api/conversation-service/agent-server-conversation-service.api.ts
+++ b/src/api/conversation-service/agent-server-conversation-service.api.ts
@@ -35,6 +35,7 @@ import {
import {
DirectConversationInfo,
assertSubscriptionAuthReady,
+ buildRouterAtStartSystemSuffix,
buildStartConversationRequestWithEncryptedSettings,
buildStartPlanningConversationRequestWithEncryptedSettings,
emptyHooksResponse,
@@ -391,6 +392,23 @@ export interface CreateConversationOptions {
// encrypted-settings builder; cloud sends it as a flat request field.
agentProfileId?: string;
agentProfileKind?: AgentKind;
+ /**
+ * Whether the first message should be routed through the active Model
+ * Router. Only consumed on the cloud path — the local path reads the
+ * toggle from its own settings fetch. Threaded in by the caller from the
+ * warmed settings query to avoid a settings round-trip on the cloud hot
+ * path.
+ */
+ runRouterAtConversationStart?: boolean;
+ /**
+ * Whether a Model Router meta-profile is currently active. The
+ * route-at-start suffix is only emitted when this is true AND
+ * ``runRouterAtConversationStart`` is on — without an active meta-profile
+ * the agent-server does not attach ``route_task_to_model``, so the
+ * instruction would tell the agent to call a tool it lacks. Threaded in
+ * by the caller from the warmed meta-profiles query.
+ */
+ hasActiveMetaProfile?: boolean;
// The LLM profile pinned to the launched agent profile (llm_profile_ref).
// When set and no explicit title_llm_profile preference exists, title
// generation uses this profile so both the agent and its title use the
@@ -462,6 +480,13 @@ class AgentServerConversationService {
// round-trip — the cloud backend holds secrets server-side.
// When launching from a profile, send `agent_profile_id`; the backend
// resolves it to agent_settings server-side.
+ // The "Run on first message" toggle is threaded in by the caller
+ // (from the warmed settings query) to avoid a settings round-trip on
+ // this hot path; the local path reads it from its own settings fetch.
+ const routerAtStartSuffix = buildRouterAtStartSystemSuffix(
+ options.runRouterAtConversationStart ?? false,
+ options.hasActiveMetaProfile ?? false,
+ );
const request: AppConversationStartRequest = {
initial_message: initialUserMsg
? {
@@ -478,6 +503,13 @@ class AgentServerConversationService {
agent_type: agentType,
sandbox_id: sandboxId ?? null,
agent_profile_id: agentProfileId ?? null,
+ ...(routerAtStartSuffix
+ ? {
+ agent_launch_additions: {
+ system_message_suffix_append: routerAtStartSuffix,
+ },
+ }
+ : {}),
trigger: "gui",
};
return createCloudAppConversation(request);
diff --git a/src/api/conversation-service/agent-server-conversation-service.types.ts b/src/api/conversation-service/agent-server-conversation-service.types.ts
index 0677deb86e..aee374982c 100644
--- a/src/api/conversation-service/agent-server-conversation-service.types.ts
+++ b/src/api/conversation-service/agent-server-conversation-service.types.ts
@@ -87,6 +87,16 @@ export interface AppConversationStartRequest {
// POST /api/v1/app-conversations; the local path uses the encrypted
// agent_settings builder instead, which threads its own agentProfileId.
agent_profile_id?: string | null;
+ /**
+ * Deployment context applied after agent resolution. The cloud app-server
+ * forwards `system_message_suffix_append` to the resolved agent's
+ * system-message suffix, mirroring the SDK's `AgentLaunchAdditions`. Used
+ * here to route the first message through the Model Router when the user
+ * enables "Run at conversation start".
+ */
+ agent_launch_additions?: {
+ system_message_suffix_append?: string | null;
+ } | null;
}
export type AppConversationStartTaskStatus =
diff --git a/src/api/settings-service/settings-service.api.ts b/src/api/settings-service/settings-service.api.ts
index 8932d66169..6bb1e58aff 100644
--- a/src/api/settings-service/settings-service.api.ts
+++ b/src/api/settings-service/settings-service.api.ts
@@ -36,6 +36,7 @@ export const APP_PREFERENCE_FIELDS = [
"title_llm_profile",
"disabled_skills",
"enabled_skills",
+ "run_router_at_conversation_start",
] as const;
export type AppPreferenceField = (typeof APP_PREFERENCE_FIELDS)[number];
diff --git a/src/components/features/settings/meta-llm-profiles/meta-llm-settings-view.tsx b/src/components/features/settings/meta-llm-profiles/meta-llm-settings-view.tsx
index c65ad85ea9..baf9d77d66 100644
--- a/src/components/features/settings/meta-llm-profiles/meta-llm-settings-view.tsx
+++ b/src/components/features/settings/meta-llm-profiles/meta-llm-settings-view.tsx
@@ -10,6 +10,9 @@ import { useProviderConnections } from "#/hooks/query/use-provider-connections";
import { useSaveMetaProfile } from "#/hooks/mutation/use-save-meta-profile";
import { useSaveLlmProfile } from "#/hooks/mutation/use-save-llm-profile";
import { useActivateMetaProfile } from "#/hooks/mutation/use-activate-meta-profile";
+import { useSettings } from "#/hooks/query/use-settings";
+import { useSaveSettings } from "#/hooks/mutation/use-save-settings";
+import { SettingsSwitch } from "#/components/features/settings/settings-switch";
import MetaProfilesService, {
type MetaProfile,
} from "#/api/meta-profiles-service/meta-profiles-service.api";
@@ -57,6 +60,8 @@ export function MetaLlmSettingsView() {
const saveMetaProfile = useSaveMetaProfile();
const saveLlmProfile = useSaveLlmProfile();
const activateMetaProfile = useActivateMetaProfile();
+ const { data: settings } = useSettings();
+ const { mutate: saveSettings } = useSaveSettings();
const [view, setView] = useState<ViewMode>("list");
const [editing, setEditing] = useState<EditingMetaProfile | null>(null);
@@ -228,6 +233,26 @@ export function MetaLlmSettingsView() {
setCreateInitial(null);
};
+ const runRouterAtConversationStart =
+ !!settings?.run_router_at_conversation_start;
+ // The toggle only does something when a router is actually active: with no
+ // active meta-profile the `route_task_to_model` tool is not attached, so
+ // routing the first message would be a no-op. Disable it then, and render
+ // it off, so the switch reflects what the agent will actually do. We do NOT
+ // auto-clear the persisted preference here: ``useMetaProfiles`` has no
+ // ``initialData``/``placeholderData``, so ``active`` is ``null`` on every
+ // mount until the fetch resolves, and a load-time effect would fire
+ // ``saveSettings({ run_router_at_conversation_start: false })`` in that
+ // window — silently destroying a user's saved preference before the
+ // meta-profiles response can prove a router is active. Instead the launch
+ // paths gate on the active meta-profile at the single suffix-emission
+ // point (``buildRouterAtStartSystemSuffix``), so a stale ``true`` with no
+ // router can never emit the ``route_task_to_model`` instruction.
+ const canRunRouterAtStart = active !== null;
+ const handleToggleRunAtConversationStart = (value: boolean) => {
+ saveSettings({ run_router_at_conversation_start: value });
+ };
+
if (isUnsupportedBackend) {
return (
<p
@@ -324,6 +349,25 @@ export function MetaLlmSettingsView() {
))}
</div>
) : null}
+
+ <div
+ className="flex flex-col gap-1 border-t border-border pt-4"
+ data-testid="meta-profile-run-at-conversation-start"
+ >
+ <SettingsSwitch
+ testId="meta-profile-run-at-conversation-start-switch"
+ isToggled={
+ canRunRouterAtStart ? runRouterAtConversationStart : false
+ }
+ isDisabled={!canRunRouterAtStart}
+ onToggle={handleToggleRunAtConversationStart}
+ >
+ {t(I18nKey.SETTINGS$META_PROFILE_RUN_AT_CONVERSATION_START)}
+ </SettingsSwitch>
+ <p className="text-xs leading-4 text-tertiary-light">
+ {t(I18nKey.SETTINGS$META_PROFILE_RUN_AT_CONVERSATION_START_HELP)}
+ </p>
+ </div>
</div>
<DeleteMetaProfileModal
diff --git a/src/hooks/mutation/use-create-conversation.ts b/src/hooks/mutation/use-create-conversation.ts
index 429ea21596..68e53b1586 100644
--- a/src/hooks/mutation/use-create-conversation.ts
+++ b/src/hooks/mutation/use-create-conversation.ts
@@ -6,6 +6,8 @@ import { Provider } from "#/types/settings";
import { useTracking } from "#/hooks/use-tracking";
import { useLlmProfiles } from "#/hooks/query/use-llm-profiles";
import { useAgentProfiles } from "#/hooks/query/use-agent-profiles";
+import { useSettings } from "#/hooks/query/use-settings";
+import { useMetaProfiles } from "#/hooks/query/use-meta-profiles";
import { useActiveBackend } from "#/contexts/active-backend-context";
import ProfilesService from "#/api/profiles-service/profiles-service.api";
import AgentProfilesService, {
@@ -74,6 +76,15 @@ export const useCreateConversation = () => {
// wrong agent.
const { backend, orgId } = useActiveBackend();
useAgentProfiles();
+ // Read the "Run on first message" toggle from the warmed settings
+ // query so the cloud path can stamp the router instruction without a
+ // settings round-trip at conversation creation. The local path reads the
+ // toggle from its own settings fetch inside the encrypted-settings builder.
+ const { data: settings } = useSettings();
+ // The active meta-profile gates the suffix on the cloud path: with no
+ // active router the agent-server does not attach `route_task_to_model`, so
+ // emitting the instruction would tell the agent to call a tool it lacks.
+ const { data: metaProfiles } = useMetaProfiles();
return useMutation({
mutationKey: CREATE_CONVERSATION_MUTATION_KEY,
@@ -275,6 +286,17 @@ export const useCreateConversation = () => {
agentLlmProfileRef: resolvedAgentProfile?.llm_profile_ref,
}
: {}),
+ // Only stamp the toggle when it's on so the default path stays
+ // byte-identical to the legacy launch (and the e2e snapshot tests
+ // that assert the exact createConversation payload). The active
+ // meta-profile gates the suffix: no router attached means no
+ // route-at-start instruction, even if the toggle was left on.
+ ...(settings?.run_router_at_conversation_start
+ ? {
+ runRouterAtConversationStart: true,
+ hasActiveMetaProfile: !!metaProfiles?.active_meta_profile,
+ }
+ : {}),
});
// Stamp the active LLM profile onto the (local) conversation so the
diff --git a/src/hooks/mutation/use-new-conversation-command.ts b/src/hooks/mutation/use-new-conversation-command.ts
index cc798c3f9e..0f86bfe4c3 100644
--- a/src/hooks/mutation/use-new-conversation-command.ts
+++ b/src/hooks/mutation/use-new-conversation-command.ts
@@ -10,6 +10,8 @@ import {
} from "#/utils/custom-toast-handlers";
import { useNavigation } from "#/context/navigation-context";
import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import { useSettings } from "#/hooks/query/use-settings";
+import { useMetaProfiles } from "#/hooks/query/use-meta-profiles";
import { useTracking } from "#/hooks/use-tracking";
export const useNewConversationCommand = () => {
@@ -17,6 +19,8 @@ export const useNewConversationCommand = () => {
const { navigate } = useNavigation();
const { t } = useTranslation("openhands");
const { data: conversation } = useActiveConversation();
+ const { data: settings } = useSettings();
+ const { data: metaProfiles } = useMetaProfiles();
const { trackConversationCreated } = useTracking();
const mutation = useMutation({
@@ -31,6 +35,16 @@ export const useNewConversationCommand = () => {
const startTask = await AgentServerConversationService.createConversation(
{
sandboxId: conversation.sandbox_id ?? undefined,
+ // Only stamp the toggle when it's on so the default /new path
+ // stays byte-identical to the legacy launch. The active
+ // meta-profile gates the suffix: no router attached means no
+ // route-at-start instruction.
+ ...(settings?.run_router_at_conversation_start
+ ? {
+ runRouterAtConversationStart: true,
+ hasActiveMetaProfile: !!metaProfiles?.active_meta_profile,
+ }
+ : {}),
},
);
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index 51dad6af97..82e53c08b7 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -6221,6 +6221,57 @@
"uk": "Метапрофілі доступні лише для локальних бекендів.",
"ca": "Els metaperfils només estan disponibles per a backends locals."
},
+ "SETTINGS$META_PROFILE_RUN_AT_CONVERSATION_START": {
+ "en": "Run on first message",
+ "ja": "最初のメッセージで実行",
+ "zh-CN": "在首条消息时运行",
+ "zh-TW": "在首則訊息時執行",
+ "ko-KR": "첫 메시지에서 실행",
+ "no": "Kjør på første melding",
+ "it": "Esegui sul primo messaggio",
+ "pt": "Executar na primeira mensagem",
+ "es": "Ejecutar en el primer mensaje",
+ "ar": "التشغيل عند أول رسالة",
+ "fr": "Exécuter sur le premier message",
+ "tr": "İlk mesajda çalıştır",
+ "de": "Bei erster Nachricht ausführen",
+ "uk": "Запускати на першому повідомленні",
+ "ca": "Executa al primer missatge"
+ },
+ "SETTINGS$META_PROFILE_RUN_AT_CONVERSATION_START_HELP": {
+ "en": "Route the first message of every new conversation through the active Model Router before the agent proceeds.",
+ "ja": "エージェントが処理を始める前に、新しい会話の最初のメッセージをアクティブなモデルルーターに振り分けます。",
+ "zh-CN": "在代理继续之前,将每个新对话的第一条消息通过当前模型路由器进行路由。",
+ "zh-TW": "在代理繼續之前,將每個新對話的第一則訊息透過目前模型路由器進行路由。",
+ "ko-KR": "에이전트가 진행하기 전에 모든 새 대화의 첫 메시지를 활성 모델 라우터로 라우팅합니다.",
+ "no": "Ruter den første meldingen i hver ny samtale gjennom den aktive modellruteren før agenten fortsetter.",
+ "it": "Instrada il primo messaggio di ogni nuova conversazione attraverso il router dei modelli attivo prima che l'agente proceda.",
+ "pt": "Encaminha a primeira mensagem de cada nova conversa pelo roteador de modelos ativo antes que o agente prossiga.",
+ "es": "Enruta el primer mensaje de cada nueva conversación a través del enrutador de modelos activo antes de que el agente continúe.",
+ "ar": "وجّه أول رسالة من كل محادثة جديدة عبر موجّه النماذج النشط قبل أن يكمل الوكيل.",
+ "fr": "Achemine le premier message de chaque nouvelle conversation via le routeur de modèles actif avant que l'agent ne continue.",
+ "tr": "Aracı devam etmeden önce her yeni konuşmanın ilk mesajını etkin model yönlendiricisi üzerinden yönlendirir.",
+ "de": "Leitet die erste Nachricht jeder neuen Konversation über den aktiven Modell-Router, bevor der Agent fortfährt.",
+ "uk": "Спрямовує перше повідомлення кожної нової розмови через активний маршрутизатор моделей, перш ніж агент продовжить.",
+ "ca": "Encamina el primer missatge de cada nova conversa a través de l'encaminador de models actiu abans que l'agent continú."
+ },
+ "SETTINGS$AGENT_PAGE_DESCRIPTION": {
+ "en": "Choose between the built-in OpenHands agent and an external ACP (Agent Client Protocol) subprocess such as Claude Code, Codex, or Gemini CLI.",
+ "ja": "組み込みのOpenHandsエージェントと、Claude Code、Codex、Gemini CLIなどの外部ACP(Agent Client Protocol)サブプロセスのどちらかを選択します。",
+ "zh-CN": "在内置的 OpenHands 代理和外部 ACP(Agent Client Protocol)子进程(如 Claude Code、Codex 或 Gemini CLI)之间进行选择。",
+ "zh-TW": "在內建的 OpenHands 代理和外部 ACP(Agent Client Protocol)子處理程序(如 Claude Code、Codex 或 Gemini CLI)之間進行選擇。",
+ "ko-KR": "내장 OpenHands 에이전트와 Claude Code, Codex, Gemini CLI 같은 외부 ACP(Agent Client Protocol) 하위 프로세스 중에서 선택하세요.",
+ "no": "Velg mellom den innebygde OpenHands-agenten og en ekstern ACP-underprosess (Agent Client Protocol) som Claude Code, Codex eller Gemini CLI.",
+ "it": "Scegli tra l'agente OpenHands integrato e un sottoprocesso ACP (Agent Client Protocol) esterno come Claude Code, Codex o Gemini CLI.",
+ "pt": "Escolha entre o agente OpenHands integrado e um subprocesso ACP (Agent Client Protocol) externo, como Claude Code, Codex ou Gemini CLI.",
+ "es": "Elige entre el agente integrado de OpenHands y un subproceso ACP (Agent Client Protocol) externo como Claude Code, Codex o Gemini CLI.",
+ "ar": "اختر بين وكيل OpenHands المدمج وعملية فرعية خارجية عبر ACP ‏(Agent Client Protocol) مثل Claude Code أو Codex أو Gemini CLI.",
+ "fr": "Choisissez entre l'agent OpenHands intégré et un sous-processus ACP (Agent Client Protocol) externe tel que Claude Code, Codex ou Gemini CLI.",
+ "tr": "Yerleşik OpenHands aracısı ile Claude Code, Codex veya Gemini CLI gibi harici bir ACP (Agent Client Protocol) alt süreci arasında seçim yapın.",
+ "de": "Wählen Sie zwischen dem integrierten OpenHands-Agenten und einem externen ACP-Subprozess (Agent Client Protocol) wie Claude Code, Codex oder Gemini CLI.",
+ "uk": "Оберіть між вбудованим агентом OpenHands і зовнішнім підпроцесом ACP (Agent Client Protocol), як-от Claude Code, Codex або Gemini CLI.",
+ "ca": "Tria entre l'agent OpenHands integrat i un subprocés ACP (Agent Client Protocol) extern com Claude Code, Codex o Gemini CLI."
+ },
"SETTINGS$AGENT_TYPE_OPENHANDS": {
"en": "OpenHands",
"ja": "OpenHands",
diff --git a/src/services/child-conversation-launch.ts b/src/services/child-conversation-launch.ts
index a07ae4ccc4..287715981d 100644
--- a/src/services/child-conversation-launch.ts
+++ b/src/services/child-conversation-launch.ts
@@ -16,6 +16,9 @@ import {
} from "#/api/conversation-metadata-store";
import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
import type { AppConversationStartTask } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { buildRouterAtStartSystemSuffix } from "#/api/agent-server-adapter";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import MetaProfilesService from "#/api/meta-profiles-service/meta-profiles-service.api";
import {
CHILD_CONVERSATION_ISOLATIONS,
CHILD_CONVERSATION_RESULT_PREFIX,
@@ -394,6 +397,21 @@ async function launchCloudChild(
}
const parentMetadata = getStoredConversationMetadata(parentConversationId);
+ // The cloud child path bypasses `createConversation`, so read the
+ // "Run on first message" toggle here to stamp the router instruction
+ // onto the launch additions (the local child path reads it inside its own
+ // settings fetch via the encrypted-settings builder). The meta-profiles
+ // fetch is gated on the toggle so the default-off path issues no extra
+ // request; when on, the suffix is only emitted if a router is actually
+ // attached — failing closed if the endpoint is unreachable.
+ const cloudSettings = await SettingsService.getSettings();
+ const cloudMetaProfiles = cloudSettings.run_router_at_conversation_start
+ ? await MetaProfilesService.listMetaProfiles().catch(() => null)
+ : null;
+ const routerAtStartSuffix = buildRouterAtStartSystemSuffix(
+ cloudSettings.run_router_at_conversation_start,
+ !!cloudMetaProfiles?.active_meta_profile,
+ );
const startTask = await createCloudAppConversation(
{
initial_message: {
@@ -415,6 +433,13 @@ async function launchCloudChild(
// Cloud. Sending it would only hide the child from the Cloud
// conversation list, which filters out anything with a parent.
parent_conversation_id: null,
+ ...(routerAtStartSuffix
+ ? {
+ agent_launch_additions: {
+ system_message_suffix_append: routerAtStartSuffix,
+ },
+ }
+ : {}),
},
backend,
);
diff --git a/src/services/settings.ts b/src/services/settings.ts
index f1a55332b3..59ab76b769 100644
--- a/src/services/settings.ts
+++ b/src/services/settings.ts
@@ -21,6 +21,7 @@ export const DEFAULT_SETTINGS: Settings = {
user_consents_to_analytics: null,
enable_proactive_conversation_starters: false,
enable_solvability_analysis: false,
+ run_router_at_conversation_start: false,
search_api_key: "",
is_new_user: true,
disabled_skills: [],
diff --git a/src/types/settings.ts b/src/types/settings.ts
index 5cbef5c02e..a4fbab30b1 100644
--- a/src/types/settings.ts
+++ b/src/types/settings.ts
@@ -135,6 +135,13 @@ export type Settings = {
enable_sound_notifications: boolean;
enable_proactive_conversation_starters: boolean;
enable_solvability_analysis: boolean;
+ /**
+ * When true and an active Model Router meta-profile is configured, the first
+ * user message of every new conversation is routed through the router (the
+ * `route_task_to_model` tool) before the agent proceeds. Default false so
+ * conversations behave exactly as before unless the user opts in.
+ */
+ run_router_at_conversation_start: boolean;
user_consents_to_analytics: boolean | null;
search_api_key?: string;
is_new_user?: boolean;