fix: harden retry alias canonicalization and endpoint coercion

Author: vicary

AGENTS.md

@@ -156,8 +156,10 @@ Canonical shape (nested):
 }
 ```
 
-Endpoint values must be explicit URLs with schemes, for example
-`redis://localhost:6379` for Redis and `http://localhost:8000/mcp` for Graphiti.
+Endpoint values must resolve to valid URLs. Config loading performs best-effort
+coercion by adding the expected scheme when omitted and defaulting the port only
+for scheme-less inputs that do not already include one (`6379` for Redis and
+`8000` for Graphiti); explicit disallowed schemes still fail validation.
 
 ## Key Files & Their Scope
 

README.md

@@ -235,9 +235,14 @@ top-level aliases remain supported for backward compatibility. Precedence is:
 1. `redis.*` (canonical)
 2. top-level Graphiti aliases such as `endpoint` and `groupIdPrefix`
 
-Endpoint values must be valid URLs, so include the scheme explicitly - for
-example `redis://localhost:6379` for Redis and `http://localhost:8000/mcp` for
-Graphiti.
+Endpoint values must resolve to valid URLs. The loader applies best-effort
+coercion for endpoint-like inputs by trimming whitespace, adding the expected
+scheme when omitted, and filling the default port only when a missing-scheme
+input also omits a port. For example, `localhost` under `redis.endpoint`
+resolves to `redis://localhost:6379`, `cache.internal:6380` resolves to
+`redis://cache.internal:6380`, and `graphiti.internal/mcp` under
+`graphiti.endpoint` resolves to `http://graphiti.internal:8000/mcp`. Inputs that
+still fail URL parsing, or that use a disallowed explicit scheme, are rejected.
 
 ### Legacy Top-Level Keys
 

src/config.test.ts

@@ -304,6 +304,84 @@ describe("config", () => {
     assertEquals(config.redis.endpoint, "rediss://cache.example:6379");
   });
 
+  it("best-effort coerces missing schemes for graphiti and redis endpoints", () => {
+    setConfigExplorerAdapterForTesting(() =>
+      makeAdapter({
+        searchResult: {
+          endpoint: "legacy.example/mcp",
+          redis: {
+            endpoint: "cache.internal",
+          },
+          graphiti: {
+            endpoint: "graphiti.internal/mcp",
+          },
+        },
+      })
+    );
+
+    const config = loadConfig();
+
+    assertEquals(config.endpoint, "http://graphiti.internal:8000/mcp");
+    assertEquals(config.graphiti.endpoint, "http://graphiti.internal:8000/mcp");
+    assertEquals(config.redis.endpoint, "redis://cache.internal:6379");
+  });
+
+  it("preserves an explicit port on scheme-less redis endpoints", () => {
+    setConfigExplorerAdapterForTesting(() =>
+      makeAdapter({
+        searchResult: {
+          redis: {
+            endpoint: "cache.internal:6380",
+          },
+        },
+      })
+    );
+
+    const config = loadConfig();
+
+    assertEquals(config.redis.endpoint, "redis://cache.internal:6380");
+  });
+
+  it("preserves explicit schemes while still requiring an allowed protocol", () => {
+    setConfigExplorerAdapterForTesting(() =>
+      makeAdapter({
+        searchResult: {
+          graphiti: {
+            endpoint: "https://secure.example/mcp",
+          },
+          redis: {
+            endpoint: "rediss://cache.example",
+          },
+        },
+      })
+    );
+
+    const config = loadConfig();
+
+    assertEquals(config.graphiti.endpoint, "https://secure.example/mcp");
+    assertEquals(config.redis.endpoint, "rediss://cache.example");
+  });
+
+  it("coerces scheme-relative endpoint inputs before validation", () => {
+    setConfigExplorerAdapterForTesting(() =>
+      makeAdapter({
+        searchResult: {
+          graphiti: {
+            endpoint: "//graphiti.internal/mcp",
+          },
+          redis: {
+            endpoint: "//cache.internal",
+          },
+        },
+      })
+    );
+
+    const config = loadConfig();
+
+    assertEquals(config.graphiti.endpoint, "http://graphiti.internal:8000/mcp");
+    assertEquals(config.redis.endpoint, "redis://cache.internal:6379");
+  });
+
   it("redacts credentials from malformed configured endpoint errors", () => {
     setConfigExplorerAdapterForTesting(() =>
       makeAdapter({

src/config.ts

@@ -137,13 +137,25 @@ const parseUrlString = (value: string | undefined): URL | null => {
   }
 };
 
-const assertExplicitUrl = (
+const URL_SCHEME_PREFIX = /^[A-Za-z][A-Za-z\d+\-.]*:\/\//;
+
+const coerceConfiguredUrl = (
   value: string | undefined,
   fieldName: string,
-  allowedSchemes?: string[],
-): void => {
-  if (value === undefined) return;
-  const url = parseUrlString(value);
+  options: {
+    allowedSchemes?: string[];
+    defaultScheme: string;
+    defaultPort?: string;
+  },
+): string | undefined => {
+  if (value === undefined) return undefined;
+
+  const hasExplicitScheme = URL_SCHEME_PREFIX.test(value);
+  const candidate = hasExplicitScheme
+    ? value
+    : `${options.defaultScheme}://${value.replace(/^\/\//, "")}`;
+
+  const url = parseUrlString(candidate);
   if (!url) {
     throw new ConfigLoadError(
       `Invalid config value for ${fieldName}: expected a valid URL, received ${
@@ -153,30 +165,62 @@ const assertExplicitUrl = (
     );
   }
   if (
-    !allowedSchemes ||
-    allowedSchemes.includes(url.protocol.slice(0, -1))
+    !options.allowedSchemes ||
+    options.allowedSchemes.includes(url.protocol.slice(0, -1))
   ) {
-    return;
+    if (!hasExplicitScheme && options.defaultPort && !url.port) {
+      url.port = options.defaultPort;
+    }
+    return url.toString();
   }
+
   throw new ConfigLoadError(
     `Invalid config value for ${fieldName}: expected URL scheme ${
-      allowedSchemes.map((scheme) => JSON.stringify(scheme)).join(" or ")
+      options.allowedSchemes.map((scheme) => JSON.stringify(scheme)).join(
+        " or ",
+      )
     }, received ${JSON.stringify(redactEndpointUserInfo(value))}`,
     { code: "config-invalid" },
   );
 };
 
-const validateExplicitConfig = (value: RawGraphitiConfig | null): void => {
-  if (!value) return;
-  assertExplicitUrl(value.endpoint, "endpoint", ["http", "https"]);
-  assertExplicitUrl(value.graphiti?.endpoint, "graphiti.endpoint", [
-    "http",
-    "https",
-  ]);
-  assertExplicitUrl(value.redis?.endpoint, "redis.endpoint", [
-    "redis",
-    "rediss",
-  ]);
+const normalizeConfiguredEndpoints = (
+  value: RawGraphitiConfig | null,
+): RawGraphitiConfig | null => {
+  if (!value) return value;
+
+  return {
+    ...value,
+    endpoint: coerceConfiguredUrl(value.endpoint, "endpoint", {
+      allowedSchemes: ["http", "https"],
+      defaultScheme: "http",
+      defaultPort: "8000",
+    }),
+    graphiti: value.graphiti
+      ? {
+        ...value.graphiti,
+        endpoint: coerceConfiguredUrl(
+          value.graphiti.endpoint,
+          "graphiti.endpoint",
+          {
+            allowedSchemes: ["http", "https"],
+            defaultScheme: "http",
+            defaultPort: "8000",
+          },
+        ),
+      }
+      : value.graphiti,
+    redis: value.redis
+      ? {
+        ...value.redis,
+        endpoint: coerceConfiguredUrl(value.redis.endpoint, "redis.endpoint", {
+          allowedSchemes: ["redis", "rediss"],
+          defaultScheme: "redis",
+          defaultPort: "6379",
+        }),
+      }
+      : value.redis,
+  };
 };
 
 const resolveNumber = (
@@ -288,8 +332,9 @@ const loadConfigFile = (
 ): RawGraphitiConfig | null => {
   try {
     const loaded = adapter?.load(filePath);
-    const normalized = loaded ? normalizeConfig(loaded.config) : null;
-    validateExplicitConfig(normalized);
+    const normalized = loaded
+      ? normalizeConfiguredEndpoints(normalizeConfig(loaded.config))
+      : null;
     return normalized;
   } catch (err) {
     if (err instanceof ConfigLoadError) throw err;
@@ -314,8 +359,9 @@ const searchConfig = (
 ): RawGraphitiConfig | null => {
   try {
     const loaded = adapter.search(directory);
-    const normalized = loaded ? normalizeConfig(loaded.config) : null;
-    validateExplicitConfig(normalized);
+    const normalized = loaded
+      ? normalizeConfiguredEndpoints(normalizeConfig(loaded.config))
+      : null;
     return normalized;
   } catch (err) {
     if (err instanceof ConfigLoadError) throw err;
@@ -349,7 +395,6 @@ export function loadConfig(directory?: string): GraphitiConfig {
     const adapter = getConfigExplorerAdapter();
     const loaded = searchConfig(adapter, directory);
     const resolved = loaded ?? loadLegacyConfig(adapter);
-    validateExplicitConfig(resolved);
     return resolveConfig(resolved);
   } catch (error) {
     if (