@vedmalex/ai-connect 0.11.0 → 0.13.0

package/README.md

@@ -611,6 +611,60 @@ Three error codes are intentionally **hard-terminal**: they never rotate, retry,
 
 All other normalized error codes (`rate_limit`, `quota_exhausted`, `temporary_unavailable`, etc.) remain eligible for the rotation/retry/fallback chain you configure under `routing.fallback`.
 
+## Connection Registry (`connections.json`)
+
+Instead of hand-writing `defineConfig(...)`, you can declare your whole topology — endpoints,
+aliases (ordered failover chains), auth, and defaults — in a single **v2 registry document** and
+compile it into the exact config the client already consumes, plus ready-made `routeHints` per
+alias. It ships as two subpaths: `@vedmalex/ai-connect/registry` (pure, browser-safe:
+`parseRegistry` / `compileRegistry` / `convertV1Registry` / `mergeRegistries`) and
+`@vedmalex/ai-connect/registry/fs` (node/bun loader: `loadConnectionRegistry` / `loadV1Pair`).
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/vedmalex/ai-connect/main/schema/connections.v2.json",
+  "version": 2,
+  "defaults": { "alias": "fast" },
+  "endpoints": [
+    {
+      "id": "openai-main",
+      "provider": "openai",
+      "transport": "api",
+      "baseUrl": "https://api.openai.com/v1",
+      "auth": { "tokenEnv": "OPENAI_API_KEY" },
+      "models": ["gpt-4.1"],
+      "defaultModel": "gpt-4.1"
+    }
+  ],
+  "aliases": [{ "id": "fast", "chain": [{ "endpointId": "openai-main" }] }]
+}
+```
+
+```ts
+import { loadConnectionRegistry } from "@vedmalex/ai-connect/registry/fs";
+import { compileRegistry } from "@vedmalex/ai-connect/registry";
+import { createLocalClient } from "@vedmalex/ai-connect";
+
+const loaded = await loadConnectionRegistry(); // layered: user → project → AI_CONNECT_CONNECTIONS
+const compiled = compileRegistry(loaded.registry, { env: (name) => process.env[name] });
+const client = createLocalClient(compiled.config);
+
+const fast = compiled.aliases["fast"];
+if (!fast?.usable) throw new Error('alias "fast" is not usable'); // never dispatch on usable:false
+
+const result = await client.generate({
+  messages: [{ role: "user", content: "Summarize this design brief." }],
+  routeHints: fast.routeHints, // ordered failover pool
+});
+console.log(result.text);
+```
+
+The loader layers `~/.config/ai-connect/connections.json` (user) under
+`<cwd>/.config/ai-connect/connections.json` (project) under `$AI_CONNECT_CONNECTIONS`, each with
+a sibling `connections.secrets.json` overlay, and auto-converts legacy v1 (`rag-endpoints.json` +
+`rag-aliases.json`) pairs. Full format, layering, failure-taxonomy, and v1-migration guide:
+[docs/connection-registry.md](./docs/connection-registry.md).
+
 ## Cancellation, Pause, and Timeouts
 
 `generate(request, opts?)` and `stream(request, opts?)` accept an optional second argument:

package/dist/browser/index.js

@@ -964,6 +964,13 @@ function normalizeTransport(providerId, input) {
     methodId: descriptor.auth.methodId.trim(),
     params: descriptor.auth.params ?? {}
   } : void 0;
+  const normalizedHeaders = (() => {
+    if (!descriptor.headers) {
+      return void 0;
+    }
+    const entries = Object.entries(descriptor.headers).map(([key, value]) => [key.trim(), value]).filter(([key]) => key.length > 0);
+    return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+  })();
   assert(
     descriptor.kind === "api" || descriptor.kind === "acp" || descriptor.kind === "cli" || descriptor.kind === "server",
     `Unsupported transport kind for provider "${providerId}".`
@@ -973,23 +980,79 @@ function normalizeTransport(providerId, input) {
       !normalizedAuth,
       `Transport auth is only supported for ACP routes. Provider "${providerId}" declared auth on a non-ACP transport.`
     );
+  }
+  if (descriptor.kind === "api") {
     assert(
       !descriptor.launch,
-      `Transport launch options are only supported for ACP routes. Provider "${providerId}" declared launch settings on a non-ACP transport.`
+      `Transport launch options are only supported for local (acp/cli/server) routes. Provider "${providerId}" declared launch settings on an api transport.`
     );
   }
+  const normalizeLaunch = () => {
+    const launchInput = descriptor.launch;
+    if (!launchInput) {
+      return void 0;
+    }
+    if (descriptor.kind !== "acp") {
+      assert(
+        launchInput.contextMode === void 0,
+        `Transport launch.contextMode is only supported for ACP routes. Provider "${providerId}" declared it on a ${descriptor.kind} transport.`
+      );
+      assert(
+        launchInput.skillsMode === void 0,
+        `Transport launch.skillsMode is only supported for ACP routes. Provider "${providerId}" declared it on a ${descriptor.kind} transport.`
+      );
+    }
+    const contextMode = launchInput.contextMode ?? "workspace";
+    const skillsMode = launchInput.skillsMode ?? "default";
+    assert(
+      contextMode === "workspace" || contextMode === "clean",
+      `Unsupported ACP contextMode "${String(contextMode)}" for provider "${providerId}".`
+    );
+    assert(
+      skillsMode === "default" || skillsMode === "disabled",
+      `Unsupported ACP skillsMode "${String(skillsMode)}" for provider "${providerId}".`
+    );
+    const env = (() => {
+      if (!launchInput.env) {
+        return void 0;
+      }
+      const entries = Object.entries(launchInput.env).map(([key, value]) => [key.trim(), value]).filter(([key]) => key.length > 0);
+      return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+    })();
+    const envPassthrough = (() => {
+      if (!launchInput.envPassthrough) {
+        return void 0;
+      }
+      const names = launchInput.envPassthrough.map((name) => String(name).trim()).filter((name) => name.length > 0);
+      return names.length > 0 ? names : void 0;
+    })();
+    return {
+      contextMode,
+      skillsMode,
+      ...env ? { env } : {},
+      ...envPassthrough ? { envPassthrough } : {}
+    };
+  };
+  const normalizedLaunch = normalizeLaunch();
   if (descriptor.kind !== "cli") {
     assert(
       !normalizedCli,
       `CLI transport options are only supported for CLI routes. Provider "${providerId}" declared cli settings on a non-CLI transport.`
     );
   }
+  if (descriptor.kind !== "api") {
+    assert(
+      !normalizedHeaders,
+      `Transport headers are only supported for API routes. Provider "${providerId}" declared headers on a non-API transport.`
+    );
+  }
   if (descriptor.kind === "api") {
     return {
       kind: "api",
       id: descriptor.id?.trim() || "api",
       ...descriptor.command?.trim() ? { command: descriptor.command.trim() } : {},
-      ...descriptor.baseUrl?.trim() ? { baseUrl: descriptor.baseUrl.trim() } : {}
+      ...descriptor.baseUrl?.trim() ? { baseUrl: descriptor.baseUrl.trim() } : {},
+      ...normalizedHeaders ? { headers: normalizedHeaders } : {}
     };
   }
   if (descriptor.kind === "cli") {
@@ -998,7 +1061,8 @@ function normalizeTransport(providerId, input) {
       kind: "cli",
       id: descriptor.id?.trim() || inferredId2,
       ...descriptor.command?.trim() ? { command: descriptor.command.trim() } : {},
-      ...normalizedCli ? { cli: normalizedCli } : {}
+      ...normalizedCli ? { cli: normalizedCli } : {},
+      ...normalizedLaunch ? { launch: normalizedLaunch } : {}
     };
   }
   if (descriptor.kind === "server") {
@@ -1007,26 +1071,11 @@ function normalizeTransport(providerId, input) {
       kind: "server",
       id: descriptor.id?.trim() || inferredId2,
       ...descriptor.command?.trim() ? { command: descriptor.command.trim() } : {},
-      ...descriptor.baseUrl?.trim() ? { baseUrl: descriptor.baseUrl.trim() } : {}
+      ...descriptor.baseUrl?.trim() ? { baseUrl: descriptor.baseUrl.trim() } : {},
+      ...normalizedLaunch ? { launch: normalizedLaunch } : {}
     };
   }
   const inferredId = ACP_TRANSPORT_ID_BY_PROVIDER[providerId] ?? "acp";
-  const normalizedLaunch = descriptor.launch ? (() => {
-    const contextMode = descriptor.launch?.contextMode ?? "workspace";
-    const skillsMode = descriptor.launch?.skillsMode ?? "default";
-    assert(
-      contextMode === "workspace" || contextMode === "clean",
-      `Unsupported ACP contextMode "${String(contextMode)}" for provider "${providerId}".`
-    );
-    assert(
-      skillsMode === "default" || skillsMode === "disabled",
-      `Unsupported ACP skillsMode "${String(skillsMode)}" for provider "${providerId}".`
-    );
-    return {
-      contextMode,
-      skillsMode
-    };
-  })() : void 0;
   return {
     kind: "acp",
     id: descriptor.id?.trim() || inferredId,
@@ -1245,12 +1294,16 @@ function normalizeOperationRouting(input, routes, defaultStrategy, resolution) {
   if (Array.isArray(input)) {
     return {
       strategy: defaultStrategy,
-      pool: resolveRouteRefs(input, routes, policy)
+      pool: resolveRouteRefs(input, routes, policy),
+      // WU-1: an explicit selector list was supplied iff it is non-empty (an empty list makes
+      // resolveRouteRefs default to all routes — indistinguishable from "no pool given").
+      explicitPool: input.length > 0
     };
   }
   return {
     strategy: input?.strategy ?? defaultStrategy,
-    pool: resolveRouteRefs(input?.pool, routes, policy)
+    pool: resolveRouteRefs(input?.pool, routes, policy),
+    explicitPool: Boolean(input?.pool && input.pool.length > 0)
   };
 }
 function finalizeRotationCapabilities(routes) {
@@ -2398,6 +2451,7 @@ var RouteRegistry = class {
       )
     ).map((route) => applyRequestedModel(route, requestedModel)).filter((route) => Boolean(route));
     const strategy = request.routeHints?.strategy ?? operationRouting.strategy;
+    const orderedPool = Boolean(request.routeHints?.pool?.length) || operationRouting.explicitPool;
     const cursorKey = `${operation}:${strategy}:${eligible.map((route) => route.id).join("|")}`;
     const healthyIds = new Set(
       eligible.filter((route) => {
@@ -2410,7 +2464,8 @@ var RouteRegistry = class {
       eligible,
       healthyIds,
       request.routeHints?.preferredProviders,
-      cursorKey
+      cursorKey,
+      orderedPool
     );
   }
   recordSuccess(route) {
@@ -2443,9 +2498,10 @@ var RouteRegistry = class {
       failureCount
     });
   }
-  #order(strategy, eligible, healthyIds, preferredProviders, cursorKey) {
-    const sorted = baseSort(eligible, preferredProviders);
-    const orderedFull = this.config.routing.shuffleOnInit ? this.#shuffle(cursorKey, sorted) : sorted;
+  #order(strategy, eligible, healthyIds, preferredProviders, cursorKey, orderedPool) {
+    const honorPoolOrder = strategy === "failover" && orderedPool;
+    const sorted = honorPoolOrder ? eligible : baseSort(eligible, preferredProviders);
+    const orderedFull = !honorPoolOrder && this.config.routing.shuffleOnInit ? this.#shuffle(cursorKey, sorted) : sorted;
     const ordered = orderedFull.filter((route) => healthyIds.has(route.id));
     const strategyFn = ROUTING_STRATEGIES[strategy];
     return strategyFn(ordered, (key, length) => this.#cursor(key, length), cursorKey);
@@ -5343,6 +5399,22 @@ function extractImagePayloads(...nodes) {
 
 // src/default-handlers.ts
 var INLINE_ATTACHMENT_TEXT_LIMIT = 16e3;
+function mergeRouteHeaders(route, builtin) {
+  const routeHeaders = route.transport.headers;
+  if (!routeHeaders || Object.keys(routeHeaders).length === 0) {
+    return builtin;
+  }
+  const builtinKeys = new Set(
+    Object.keys(builtin).map((key) => key.toLowerCase())
+  );
+  const passthrough = {};
+  for (const [key, value] of Object.entries(routeHeaders)) {
+    if (!builtinKeys.has(key.toLowerCase())) {
+      passthrough[key] = value;
+    }
+  }
+  return { ...passthrough, ...builtin };
+}
 function trimTrailingSlash(value) {
   return value.replace(/\/+$/, "");
 }
@@ -5967,9 +6039,9 @@ async function discoverOpenAiModels(fetchImpl, context) {
   discoveryTransportSummary(context, "openai-models", endpoint, "GET");
   const response = await fetchImpl(endpoint, {
     method: "GET",
-    headers: {
+    headers: mergeRouteHeaders(context.route, {
       authorization: `Bearer ${apiKey}`
-    },
+    }),
     signal: context.abort.signal
   });
   const payload = await readPayload(response);
@@ -5984,10 +6056,10 @@ async function discoverAnthropicModels(fetchImpl, context) {
   discoveryTransportSummary(context, "anthropic-models", endpoint, "GET");
   const response = await fetchImpl(endpoint, {
     method: "GET",
-    headers: {
+    headers: mergeRouteHeaders(context.route, {
       "x-api-key": apiKey,
       "anthropic-version": "2023-06-01"
-    },
+    }),
     signal: context.abort.signal
   });
   const payload = await readPayload(response);
@@ -6002,7 +6074,7 @@ async function discoverGeminiModels(fetchImpl, context) {
   discoveryTransportSummary(context, "gemini-models", endpoint, "GET");
   const response = await fetchImpl(endpoint, {
     method: "GET",
-    headers: geminiApiKeyHeaders(apiKey),
+    headers: mergeRouteHeaders(context.route, geminiApiKeyHeaders(apiKey)),
     signal: context.abort.signal
   });
   const payload = await readPayload(response);
@@ -6215,11 +6287,11 @@ async function uploadAnthropicFile(payload, uploader) {
     );
     const response = await uploader.fetchImpl(endpoint, {
       method: "POST",
-      headers: {
+      headers: mergeRouteHeaders(uploader.context.route, {
         "x-api-key": uploader.apiKey,
         "anthropic-version": "2023-06-01",
         "anthropic-beta": "files-api-2025-04-14"
-      },
+      }),
       body: form,
       signal: uploader.context.abort.signal
     });
@@ -6253,9 +6325,9 @@ async function uploadOpenAiFile(payload, uploader) {
     form.append("purpose", "user_data");
     const response = await uploader.fetchImpl(endpoint, {
       method: "POST",
-      headers: {
+      headers: mergeRouteHeaders(uploader.context.route, {
         authorization: `Bearer ${uploader.apiKey}`
-      },
+      }),
       body: form,
       signal: uploader.context.abort.signal
     });
@@ -6285,12 +6357,12 @@ async function uploadGeminiFile(payload, uploader) {
     ) : "https://generativelanguage.googleapis.com/upload/v1beta/files";
     const response = await uploader.fetchImpl(endpoint, {
       method: "POST",
-      headers: {
+      headers: mergeRouteHeaders(uploader.context.route, {
         ...geminiApiKeyHeaders(uploader.apiKey),
         "X-Goog-Upload-Protocol": "raw",
         "X-Goog-Upload-Header-Content-Type": payload.mimeType,
         "content-type": payload.mimeType
-      },
+      }),
       body: base64ToBlob(payload.base64, payload.mimeType),
       signal: uploader.context.abort.signal
     });
@@ -6872,10 +6944,10 @@ async function runOpenAi(fetchImpl, context) {
     transportSummary(context, "openai-chat", endpoint, "POST", false, body);
     const response = await fetchImpl(endpoint, {
       method: "POST",
-      headers: {
+      headers: mergeRouteHeaders(context.route, {
         "content-type": "application/json",
         authorization: `Bearer ${apiKey}`
-      },
+      }),
       body: JSON.stringify(body),
       signal: context.abort.signal
     });
@@ -6954,10 +7026,10 @@ async function* runOpenAiStream(fetchImpl, context) {
     transportSummary(context, "openai-chat", endpoint, "POST", true, body);
     const response2 = await fetchImpl(endpoint, {
       method: "POST",
-      headers: {
+      headers: mergeRouteHeaders(context.route, {
         "content-type": "application/json",
         authorization: `Bearer ${apiKey}`
-      },
+      }),
       body: JSON.stringify(body),
       signal: context.abort.signal
     });
@@ -7162,15 +7234,15 @@ async function runProviderImage(fetchImpl, context, opts) {
   );
   const response = await fetchImpl(endpoint, useEditEndpoint ? {
     method: "POST",
-    headers: { ...opts.authHeaders },
+    headers: mergeRouteHeaders(context.route, { ...opts.authHeaders }),
     body: await buildImageEditFormData(context, baseFields),
     signal: context.abort.signal
   } : {
     method: "POST",
-    headers: {
+    headers: mergeRouteHeaders(context.route, {
       "content-type": "application/json",
       ...opts.authHeaders
-    },
+    }),
     body: JSON.stringify(baseFields),
     signal: context.abort.signal
   });
@@ -7225,11 +7297,11 @@ async function runAnthropic(fetchImpl, context) {
   transportSummary(context, "anthropic-messages", endpoint, "POST", false, requestBody);
   const response = await fetchImpl(endpoint, {
     method: "POST",
-    headers: {
+    headers: mergeRouteHeaders(context.route, {
       "content-type": "application/json",
       "x-api-key": apiKey,
       "anthropic-version": "2023-06-01"
-    },
+    }),
     body: JSON.stringify(requestBody),
     signal: context.abort.signal
   });
@@ -7294,10 +7366,10 @@ async function runGemini(fetchImpl, context) {
   transportSummary(context, "gemini-generate-content", endpoint, "POST", false, requestBody);
   const response = await fetchImpl(endpoint, {
     method: "POST",
-    headers: {
+    headers: mergeRouteHeaders(context.route, {
       ...geminiApiKeyHeaders(apiKey),
       "content-type": "application/json"
-    },
+    }),
     body: JSON.stringify(requestBody),
     signal: context.abort.signal
   });