From 325188eb9bd157fc62df36e73e75a5a1d5df81da Mon Sep 17 00:00:00 2001
From: Diego Rodrigues de Sa e Souza
 <8016841+diegosouzapw@users.noreply.github.com>
Date: Thu, 25 Jun 2026 07:25:59 -0300
Subject: [PATCH] feat(combos): add editable per-combo description field
 persisted via /api/combos (#5005) (#5011)

* feat(combos): add editable per-combo description field persisted via /api/combos (#5005)

* docs(changelog): restore #3981/#5003/#4665 entries eaten by merge

---------

Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
---
 CHANGELOG.md                                  |  1 +
 config/quality/file-size-baseline.json        |  2 +-
 src/app/(dashboard)/dashboard/combos/page.tsx | 29 ++++++
 src/i18n/messages/en.json                     |  2 +
 src/shared/validation/schemas/combo.ts        |  3 +
 tests/unit/combo-description-5005.test.ts     | 91 +++++++++++++++++++
 6 files changed, 127 insertions(+), 1 deletion(-)
 create mode 100644 tests/unit/combo-description-5005.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f4750ed3f..581102f839 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@
 _In development — bullets added per PR; finalized at release._
 
 - **feat(providers):** update volcengine-ark model list, adding DeepSeek-V4-Flash and DeepSeek-V4-Pro. (thanks @kenlin8827)
+- **feat(combos):** add an editable per-combo `description` field. The routing-combo form now has a Description input, persisted in the combo `data` blob via `/api/combos` (POST/PUT) and round-tripped through GET — no new DB column ([#5005](https://github.com/diegosouzapw/OmniRoute/issues/5005)).
 
 ### 🔧 Bug Fixes
 
diff --git a/config/quality/file-size-baseline.json b/config/quality/file-size-baseline.json
index 46d0145309..7daf81bcf0 100644
--- a/config/quality/file-size-baseline.json
+++ b/config/quality/file-size-baseline.json
@@ -165,7 +165,7 @@
     "src/app/(dashboard)/dashboard/cache/page.tsx": 845,
     "src/app/(dashboard)/dashboard/cli-code/components/CodexToolCard.tsx": 900,
     "src/app/(dashboard)/dashboard/cloud-agents/page.tsx": 922,
-    "src/app/(dashboard)/dashboard/combos/page.tsx": 4456,
+    "src/app/(dashboard)/dashboard/combos/page.tsx": 4485,
     "src/app/(dashboard)/dashboard/costs/CostOverviewTab.tsx": 1495,
     "src/app/(dashboard)/dashboard/costs/quota-share/components/PoolWizard.tsx": 1007,
     "src/app/(dashboard)/dashboard/endpoint/EndpointPageClient.tsx": 2570,
diff --git a/src/app/(dashboard)/dashboard/combos/page.tsx b/src/app/(dashboard)/dashboard/combos/page.tsx
index b64dcbd959..985ad22758 100644
--- a/src/app/(dashboard)/dashboard/combos/page.tsx
+++ b/src/app/(dashboard)/dashboard/combos/page.tsx
@@ -1947,6 +1947,7 @@ function ComboFormModal({ isOpen, combo, onClose, onSave, activeProviders, combo
   const isExpertMode = normalizeComboConfigMode(comboConfigMode) === "expert";
   const createDraftStateRef = useRef<CreateDraftSnapshot>(getEmptyCreateDraftSnapshot());
   const [name, setName] = useState(combo?.name || "");
+  const [description, setDescription] = useState<string>(combo?.description || "");
   const [models, setModels] = useState(() => {
     return (combo?.models || []).map((m) => normalizeModelEntry(m));
   });
@@ -2007,6 +2008,7 @@ function ComboFormModal({ isOpen, combo, onClose, onSave, activeProviders, combo
           );
 
       setName(nextCombo?.name || "");
+      setDescription(nextCombo?.description || "");
       setModels((nextCombo?.models || []).map((m) => normalizeModelEntry(m)));
       setStrategy(nextCombo?.strategy || comboDefaults?.strategy || "priority");
       setConfig(nextConfig);
@@ -2738,6 +2740,14 @@ function ComboFormModal({ isOpen, combo, onClose, onSave, activeProviders, combo
       strategy,
     };
 
+    // Per-combo description (#5005). Free-text, optional, persisted in combo data.
+    if (description.trim()) {
+      saveData.description = description.trim();
+    } else if (isEdit) {
+      // Editing: send null to explicitly clear a previously-set description.
+      saveData.description = null;
+    }
+
     // Include config only if any values are set
     const configToSave = sanitizeComboRuntimeConfig(config);
     // Add round-robin specific fields to config
@@ -2924,6 +2934,25 @@ function ComboFormModal({ isOpen, combo, onClose, onSave, activeProviders, combo
                 )}
               </div>
 
+              {/* Description (#5005) — optional free-text note for this combo */}
+              <div>
+                <label className="text-[11px] font-medium text-text-muted block mb-0.5">
+                  {getI18nOrFallback(t, "comboDescription", "Description")}
+                </label>
+                <textarea
+                  rows={2}
+                  data-testid="combo-description-input"
+                  value={description}
+                  onChange={(e) => setDescription(e.target.value)}
+                  placeholder={getI18nOrFallback(
+                    t,
+                    "comboDescriptionPlaceholder",
+                    "Optional note describing this combo"
+                  )}
+                  className="w-full text-xs py-1.5 px-2 rounded border border-black/10 dark:border-white/10 bg-transparent focus:border-primary focus:outline-none resize-none"
+                />
+              </div>
+
               {!isEdit && !isExpertMode && (
                 <div className="rounded-lg border border-black/8 dark:border-white/8 bg-black/[0.02] dark:bg-white/[0.02] p-3">
                   <div className="mb-2">
diff --git a/src/i18n/messages/en.json b/src/i18n/messages/en.json
index 87c70696fc..480e740705 100644
--- a/src/i18n/messages/en.json
+++ b/src/i18n/messages/en.json
@@ -2345,6 +2345,8 @@
     "leastLatency": "Least Latency",
     "comboName": "Combo Name",
     "comboNamePlaceholder": "my-combo",
+    "comboDescription": "Description",
+    "comboDescriptionPlaceholder": "Optional note describing this combo",
     "deleteConfirm": "Delete this combo?",
     "noCombosYet": "No combos yet",
     "comboCreated": "Combo created successfully",
diff --git a/src/shared/validation/schemas/combo.ts b/src/shared/validation/schemas/combo.ts
index 64874daa3b..8590ff9ebf 100644
--- a/src/shared/validation/schemas/combo.ts
+++ b/src/shared/validation/schemas/combo.ts
@@ -220,6 +220,7 @@ export const comboNameSchema = z
 
 export const createComboSchema = z.object({
   name: comboNameSchema,
+  description: z.string().max(2000).optional(),
   models: z.array(comboModelEntry).optional().default([]),
   strategy: comboStrategySchema.optional().default("priority"),
   config: comboRuntimeConfigSchema.optional(),
@@ -266,6 +267,7 @@ export const updateComboDefaultsSchema = z
 export const updateComboSchema = z
   .object({
     name: comboNameSchema.optional(),
+    description: z.string().max(2000).optional().nullable(),
     models: z.array(comboModelEntry).optional(),
     strategy: comboStrategySchema.optional(),
     config: comboRuntimeConfigSchema.optional(),
@@ -280,6 +282,7 @@ export const updateComboSchema = z
   .superRefine((value, ctx) => {
     if (
       value.name === undefined &&
+      value.description === undefined &&
       value.models === undefined &&
       value.strategy === undefined &&
       value.config === undefined &&
diff --git a/tests/unit/combo-description-5005.test.ts b/tests/unit/combo-description-5005.test.ts
new file mode 100644
index 0000000000..c77a6a9185
--- /dev/null
+++ b/tests/unit/combo-description-5005.test.ts
@@ -0,0 +1,91 @@
+/**
+ * #5005 — Per-combo editable `description` field.
+ *
+ * The routing-combo API historically had NO `description` field: the Zod
+ * `createComboSchema` / `updateComboSchema` stripped any `description` on save.
+ * This proves the schema now ACCEPTS and PRESERVES `description`, and that the
+ * value round-trips through the DB layer (persisted in the `data` JSON blob and
+ * surfaced back by GET-style reads), with no new DB column.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-combo-desc-5005-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+
+const { createComboSchema, updateComboSchema } = await import(
+  "../../src/shared/validation/schemas.ts"
+);
+const core = await import("../../src/lib/db/core.ts");
+const combosDb = await import("../../src/lib/db/combos.ts");
+
+async function resetStorage() {
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+}
+
+test.beforeEach(async () => {
+  await resetStorage();
+});
+
+test.after(async () => {
+  core.resetDbInstance();
+  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+});
+
+test("createComboSchema preserves description instead of stripping it", () => {
+  const parsed = createComboSchema.parse({
+    name: "Described Combo",
+    models: [{ provider: "openai", model: "gpt-4.1" }],
+    description: "Routes premium traffic to GPT-4.1",
+  });
+  assert.equal(parsed.description, "Routes premium traffic to GPT-4.1");
+});
+
+test("updateComboSchema preserves description instead of stripping it", () => {
+  const parsed = updateComboSchema.parse({
+    description: "Updated description text",
+  });
+  assert.equal(parsed.description, "Updated description text");
+});
+
+test("description round-trips through createCombo and getComboById/getComboByName", async () => {
+  const created = await combosDb.createCombo({
+    name: "Desc Combo",
+    models: [{ provider: "openai", model: "gpt-4.1" }],
+    description: "My human-friendly note",
+  });
+  assert.equal(created.description, "My human-friendly note");
+
+  const byId = await combosDb.getComboById(created.id as string);
+  assert.ok(byId, "combo should be retrievable by id");
+  assert.equal(byId!.description, "My human-friendly note");
+
+  const byName = await combosDb.getComboByName("Desc Combo");
+  assert.ok(byName, "combo should be retrievable by name");
+  assert.equal(byName!.description, "My human-friendly note");
+});
+
+test("description survives an updateCombo and is listed by getCombos", async () => {
+  const created = await combosDb.createCombo({
+    name: "Update Desc Combo",
+    models: [{ provider: "openai", model: "gpt-4.1" }],
+  });
+
+  const updated = await combosDb.updateCombo(created.id as string, {
+    description: "Added later via PUT",
+  });
+  assert.ok(updated);
+  assert.equal(updated!.description, "Added later via PUT");
+
+  const all = await combosDb.getCombos();
+  const found = all.find((c) => c.id === created.id);
+  assert.ok(found, "updated combo should appear in getCombos");
+  assert.equal(found!.description, "Added later via PUT");
+});