fix(proxy): merge User-Agent via Headers so applySearchRequestConfig preserves any HeadersInit shape (BUG-009)

Addresses Copilot review on PR #145: the object-spread merge could silently
drop existing headers if a caller passed a Headers instance or tuple-array
HeadersInit. Normalize through a Headers instance and write the result back as
a plain object, so already-set headers are preserved regardless of shape. Both
current callers pass no prior headers, so behavior is unchanged; the four UA
assertions now read the normalized lowercase `user-agent` key.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ihor-sokoliuk

__tests__/unit/instance-info.test.ts

@@ -455,7 +455,7 @@ async function runTests() {
     await fetchInstanceInfo(mockServer as any);
 
     const headers = getCapturedOptions()?.headers as Record<string, string>;
-    assert.equal(headers?.['User-Agent'], 'MyBot/1.0');
+    assert.equal(headers?.['user-agent'], 'MyBot/1.0');
 
     fetchMocker.restore();
     envManager.restore();
@@ -475,7 +475,7 @@ async function runTests() {
     await fetchInstanceInfo(mockServer as any);
 
     const headers = (getCapturedOptions()?.headers || {}) as Record<string, string>;
-    assert.ok(!headers['User-Agent'], `Expected no User-Agent header`);
+    assert.ok(!headers['user-agent'], `Expected no User-Agent header`);
 
     fetchMocker.restore();
     envManager.restore();

__tests__/unit/suggestions.test.ts

@@ -184,7 +184,7 @@ async function runTests() {
     await performSearchSuggestions(mockServer as any, 'type');
 
     const headers = getCapturedOptions()?.headers as Record<string, string>;
-    assert.equal(headers?.['User-Agent'], 'MyBot/1.0');
+    assert.equal(headers?.['user-agent'], 'MyBot/1.0');
 
     fetchMocker.restore();
     envManager.restore();
@@ -204,7 +204,7 @@ async function runTests() {
     await performSearchSuggestions(mockServer as any, 'type');
 
     const headers = (getCapturedOptions()?.headers || {}) as Record<string, string>;
-    assert.ok(!headers['User-Agent'], `Expected no User-Agent header`);
+    assert.ok(!headers['user-agent'], `Expected no User-Agent header`);
 
     fetchMocker.restore();
     envManager.restore();

src/proxy.ts

@@ -297,10 +297,10 @@ export function createDefaultAgent(): Agent | undefined {
  * still builds its own options in `search.ts` (Basic-Auth handling is interleaved
  * there); folding it in here is tracked under FEAT-050.
  *
- * Callers pass a freshly-built `RequestInit`; `headers`, when already present, is a
- * plain object (the convention across this codebase), so the spread-merge preserves
- * any existing entries — other `HeadersInit` shapes (a `Headers` instance or tuple
- * array) are never passed here and are intentionally not normalized.
+ * The User-Agent is merged through a `Headers` instance, so any already-set
+ * `headers` — whether a plain object, a `Headers` instance, or a tuple array —
+ * is preserved; the result is written back as a plain object. (In practice both
+ * callers pass a freshly-built `RequestInit` with no prior headers.)
  */
 export function applySearchRequestConfig(
   requestOptions: RequestInit,
@@ -314,10 +314,12 @@ export function applySearchRequestConfig(
 
   const userAgent = process.env.USER_AGENT;
   if (userAgent) {
-    requestOptions.headers = {
-      ...requestOptions.headers,
-      "User-Agent": userAgent,
-    };
+    // Normalize via Headers so any HeadersInit shape (plain object, Headers
+    // instance, or tuple array) merges without dropping already-set entries,
+    // then hand back a plain object.
+    const headers = new Headers(requestOptions.headers);
+    headers.set("User-Agent", userAgent);
+    requestOptions.headers = Object.fromEntries(headers);
   }
 }