fix(roo): use separate versionedSettings field for backward compatibility

Address review feedback from @mrubens: Old clients expect plain values
in the settings field (e.g., includedTools as array of strings).

Changes:
- Add new versionedSettings field to RooModelSchema for version-gated values
- Keep settings field for plain values (backward compatible with old clients)
- New clients read from both fields: settings first, then overlay versionedSettings
- Update documentation to clarify the two-field approach
- Add tests for versionedSettings overlay behavior

Author: hannesrudolph

packages/types/src/providers/roo.ts

@@ -41,7 +41,13 @@ export const RooModelSchema = z.object({
 	default_temperature: z.number().optional(),
 	// Dynamic settings that map directly to ModelInfo properties
 	// Allows the API to configure model-specific defaults like includedTools, excludedTools, reasoningEffort, etc.
+	// These are always direct values (e.g., includedTools: ['search_replace']) for backward compatibility with old clients.
 	settings: z.record(z.string(), z.unknown()).optional(),
+	// Versioned settings that are gated behind minimum plugin versions.
+	// Each value is an object with { value: T, minPluginVersion: string }.
+	// New clients check this field first and resolve based on current plugin version.
+	// Old clients ignore this field and use plain values from `settings`.
+	versionedSettings: z.record(z.string(), z.unknown()).optional(),
 })
 
 export const RooModelsResponseSchema = z.object({

src/api/providers/fetchers/__tests__/roo.spec.ts

@@ -801,4 +801,140 @@ describe("getRooModels", () => {
 		expect(model.anotherSetting).toBe(42)
 		expect(model.nestedConfig).toEqual({ key: "value" })
 	})
+
+	it("should apply versioned settings on top of plain settings", async () => {
+		const mockResponse = {
+			object: "list",
+			data: [
+				{
+					id: "test/versioned-model",
+					object: "model",
+					created: 1234567890,
+					owned_by: "test",
+					name: "Model with Versioned Settings",
+					description: "Model with versioned settings",
+					context_window: 128000,
+					max_tokens: 8192,
+					type: "language",
+					tags: ["tool-use"],
+					pricing: {
+						input: "0.0001",
+						output: "0.0002",
+					},
+					// Plain settings for backward compatibility with old clients
+					settings: {
+						includedTools: ["apply_patch"],
+						excludedTools: ["write_to_file"],
+					},
+					// Versioned settings for new clients (low version requirement, always met)
+					versionedSettings: {
+						includedTools: {
+							value: ["apply_patch", "search_replace"],
+							minPluginVersion: "1.0.0", // Very low version - always met
+						},
+						excludedTools: {
+							value: ["apply_diff", "write_to_file"],
+							minPluginVersion: "1.0.0", // Very low version - always met
+						},
+					},
+				},
+			],
+		}
+
+		mockFetch.mockResolvedValueOnce({
+			ok: true,
+			json: async () => mockResponse,
+		})
+
+		const models = await getRooModels(baseUrl, apiKey)
+
+		// Versioned settings should override plain settings
+		expect(models["test/versioned-model"].includedTools).toEqual(["apply_patch", "search_replace"])
+		expect(models["test/versioned-model"].excludedTools).toEqual(["apply_diff", "write_to_file"])
+	})
+
+	it("should use plain settings when versioned settings version requirement is not met", async () => {
+		const mockResponse = {
+			object: "list",
+			data: [
+				{
+					id: "test/old-version-model",
+					object: "model",
+					created: 1234567890,
+					owned_by: "test",
+					name: "Model for Old Version",
+					description: "Model with versioned settings for newer version",
+					context_window: 128000,
+					max_tokens: 8192,
+					type: "language",
+					tags: ["tool-use"],
+					pricing: {
+						input: "0.0001",
+						output: "0.0002",
+					},
+					settings: {
+						includedTools: ["apply_patch"],
+					},
+					versionedSettings: {
+						// Very high version requirement - never met
+						includedTools: {
+							value: ["apply_patch", "search_replace"],
+							minPluginVersion: "99.0.0",
+						},
+					},
+				},
+			],
+		}
+
+		mockFetch.mockResolvedValueOnce({
+			ok: true,
+			json: async () => mockResponse,
+		})
+
+		const models = await getRooModels(baseUrl, apiKey)
+
+		// Should use plain settings since versioned requirement is not met
+		expect(models["test/old-version-model"].includedTools).toEqual(["apply_patch"])
+	})
+
+	it("should handle model with only versionedSettings and no plain settings", async () => {
+		const mockResponse = {
+			object: "list",
+			data: [
+				{
+					id: "test/versioned-only-model",
+					object: "model",
+					created: 1234567890,
+					owned_by: "test",
+					name: "Model with Only Versioned Settings",
+					description: "Model with only versioned settings",
+					context_window: 128000,
+					max_tokens: 8192,
+					type: "language",
+					tags: [],
+					pricing: {
+						input: "0.0001",
+						output: "0.0002",
+					},
+					// No plain settings, only versionedSettings
+					versionedSettings: {
+						customFeature: {
+							value: true,
+							minPluginVersion: "1.0.0", // Low version, should always be met
+						},
+					},
+				},
+			],
+		}
+
+		mockFetch.mockResolvedValueOnce({
+			ok: true,
+			json: async () => mockResponse,
+		})
+
+		const models = await getRooModels(baseUrl, apiKey)
+		const model = models["test/versioned-only-model"] as any
+
+		expect(model.customFeature).toBe(true)
+	})
 })

src/api/providers/fetchers/roo.ts

@@ -129,18 +129,33 @@ export async function getRooModels(baseUrl: string, apiKey?: string): Promise<Mo
 				// Apply API-provided settings on top of base model info
 				// Settings allow the proxy to dynamically configure model-specific options
 				// like includedTools, excludedTools, reasoningEffort, etc.
-				// Settings can be versioned with minPluginVersion to gate features by plugin version:
-				// - Direct values: { includedTools: ['search_replace'] }
-				// - Versioned values: { includedTools: { value: ['search_replace'], minPluginVersion: '3.36.4' } }
+				//
+				// Two fields are used for backward compatibility:
+				// - `settings`: Plain values that work with all client versions (e.g., { includedTools: ['search_replace'] })
+				// - `versionedSettings`: Values gated by minPluginVersion (e.g., { includedTools: { value: ['search_replace'], minPluginVersion: '3.36.4' } })
+				//
+				// New clients process both fields - settings first, then overlay resolved versionedSettings.
+				// Old clients only see `settings` and ignore `versionedSettings`.
 				const apiSettings = model.settings as Record<string, unknown> | undefined
+				const apiVersionedSettings = model.versionedSettings as Record<string, unknown> | undefined
 
+				// Start with base model info
+				let modelInfo: ModelInfo = { ...baseModelInfo }
+
+				// Apply plain settings (backward compatible with old clients)
 				if (apiSettings) {
-					// Resolve versioned settings based on current plugin version
-					const resolvedSettings = resolveVersionedSettings(apiSettings) as Partial<ModelInfo>
-					models[modelId] = { ...baseModelInfo, ...resolvedSettings }
-				} else {
-					models[modelId] = baseModelInfo
+					modelInfo = { ...modelInfo, ...(apiSettings as Partial<ModelInfo>) }
+				}
+
+				// Apply versioned settings (new clients only - resolved based on plugin version)
+				if (apiVersionedSettings) {
+					const resolvedVersionedSettings = resolveVersionedSettings(
+						apiVersionedSettings,
+					) as Partial<ModelInfo>
+					modelInfo = { ...modelInfo, ...resolvedVersionedSettings }
 				}
+
+				models[modelId] = modelInfo
 			}
 
 			return models

src/api/providers/fetchers/versionedSettings.ts

@@ -6,12 +6,22 @@ import { Package } from "../../../shared/package"
  * Schema for a versioned setting value.
  * Allows settings to be gated behind a minimum plugin version.
  *
- * Example:
+ * These values should be placed in the `versionedSettings` field of the API response,
+ * separate from the plain `settings` field. This ensures backward compatibility:
+ * - Old clients read from `settings` (plain values only)
+ * - New clients read from both `settings` and `versionedSettings`
+ *
+ * Example API response:
  * ```
  * {
- *   includedTools: {
- *     value: ['search_replace'],
- *     minPluginVersion: '3.36.4',
+ *   settings: {
+ *     includedTools: ['search_replace']  // Plain value for old clients
+ *   },
+ *   versionedSettings: {
+ *     includedTools: {
+ *       value: ['search_replace', 'apply_diff'],  // Enhanced value for new clients
+ *       minPluginVersion: '3.36.4',
+ *     }
  *   }
  * }
  * ```