fix(config): append numeric bounds in validation errors

alchip · alchip · commit 01fcc4b512d5 · 2026-04-28T11:32:08.000+08:00
diff --git a/src/config/validation.allowed-values.test.ts b/src/config/validation.allowed-values.test.ts
@@ -44,6 +44,25 @@ describe("config validation allowed-values metadata", () => {
     expect(issue.allowedValuesHiddenCount).toBe(0);
   });
 
+  it("appends numeric max constraints to schema errors", () => {
+    const result = validateConfigObjectRaw({
+      session: {
+        agentToAgent: {
+          maxPingPongTurns: 10,
+        },
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      const issue = result.issues.find(
+        (entry) => entry.path === "session.agentToAgent.maxPingPongTurns",
+      );
+      expect(issue).toBeDefined();
+      expect(issue?.message).toContain("maximum allowed value is 5");
+    }
+  });
+
   it("includes boolean variants for boolean-or-enum unions", () => {
     const issue = __testing.mapZodIssueToConfigIssue({
       code: "custom",
diff --git a/src/config/validation.ts b/src/config/validation.ts
@@ -484,10 +484,33 @@ function collectLegacySecretRefEnvMarkerIssues(raw: unknown): ConfigValidationIs
   }));
 }
 
+function appendNumericConstraintHint(record: UnknownIssueRecord | null, message: string): string {
+  if (!record || typeof record.code !== "string") {
+    return message;
+  }
+
+  if (record.code === "too_big") {
+    const maximum = typeof record.maximum === "number" ? record.maximum : null;
+    if (maximum !== null) {
+      return `${message} (maximum allowed value is ${maximum})`;
+    }
+  }
+
+  if (record.code === "too_small") {
+    const minimum = typeof record.minimum === "number" ? record.minimum : null;
+    if (minimum !== null) {
+      return `${message} (minimum allowed value is ${minimum})`;
+    }
+  }
+
+  return message;
+}
+
 function mapZodIssueToConfigIssue(issue: unknown): ConfigValidationIssue {
   const record = toIssueRecord(issue);
   const path = formatConfigPath(toConfigPathSegments(record?.path));
-  const message = typeof record?.message === "string" ? record.message : "Invalid input";
+  const rawMessage = typeof record?.message === "string" ? record.message : "Invalid input";
+  const message = appendNumericConstraintHint(record, rawMessage);
 
   const allowedValuesSummary = summarizeAllowedValues(collectAllowedValuesFromUnknownIssue(issue));
 
