@vedmalex/ai-connect 0.10.0 → 0.11.0

package/dist/browser/index.js

@@ -197,6 +197,373 @@ function toAiConnectError(error, fallbackCode = "temporary_unavailable") {
   return new AiConnectError(fallbackCode, "Unknown route failure.");
 }
 
+// src/model-reference.ts
+var DEFAULT_CONTEXT_WINDOW = 8192;
+var CHAT_CAPS = { vision: true, tools: true };
+var MODEL_REFERENCE = {
+  // --- OpenAI (gpt / codex families; catalog: gpt-4.1, gpt-5.4/xhigh) ---
+  "gpt-4.1": { key: "gpt-4.1", contextLength: 1047576, capabilities: CHAT_CAPS },
+  "gpt-4.1-mini": {
+    key: "gpt-4.1-mini",
+    contextLength: 1047576,
+    capabilities: CHAT_CAPS
+  },
+  "gpt-4.1-nano": {
+    key: "gpt-4.1-nano",
+    contextLength: 1047576,
+    capabilities: CHAT_CAPS
+  },
+  "gpt-4o": { key: "gpt-4o", contextLength: 128e3, capabilities: CHAT_CAPS },
+  "gpt-4o-mini": {
+    key: "gpt-4o-mini",
+    contextLength: 128e3,
+    capabilities: CHAT_CAPS
+  },
+  "gpt-4-turbo": {
+    key: "gpt-4-turbo",
+    contextLength: 128e3,
+    capabilities: CHAT_CAPS
+  },
+  // Exception (F-D4-2-1): gpt-4 is not vision-capable.
+  "gpt-4": {
+    key: "gpt-4",
+    contextLength: 8192,
+    capabilities: { vision: false, tools: true }
+  },
+  // Exception (F-D4-2-1): gpt-3.5-turbo is not vision-capable.
+  "gpt-3.5-turbo": {
+    key: "gpt-3.5-turbo",
+    contextLength: 16385,
+    capabilities: { vision: false, tools: true }
+  },
+  "gpt-5": { key: "gpt-5", contextLength: 4e5, capabilities: CHAT_CAPS },
+  "gpt-5.4": { key: "gpt-5.4", contextLength: 4e5, capabilities: CHAT_CAPS },
+  o1: { key: "o1", contextLength: 2e5, capabilities: CHAT_CAPS },
+  // F-D4-2-1: o1-mini is neither vision- nor tool-capable.
+  "o1-mini": {
+    key: "o1-mini",
+    contextLength: 128e3,
+    capabilities: { vision: false, tools: false }
+  },
+  // Exception (F-D4-2-1): o3-mini is not vision-capable (tools remain supported).
+  "o3-mini": {
+    key: "o3-mini",
+    contextLength: 2e5,
+    capabilities: { vision: false, tools: true }
+  },
+  // --- Anthropic (claude families; catalog: claude-sonnet-4-6, claude-sonnet-4) ---
+  "claude-sonnet-4-6": {
+    key: "claude-sonnet-4-6",
+    contextLength: 2e5,
+    capabilities: CHAT_CAPS
+  },
+  "claude-sonnet-4": {
+    key: "claude-sonnet-4",
+    contextLength: 2e5,
+    capabilities: CHAT_CAPS
+  },
+  "claude-opus-4": {
+    key: "claude-opus-4",
+    contextLength: 2e5,
+    capabilities: CHAT_CAPS
+  },
+  "claude-haiku-4": {
+    key: "claude-haiku-4",
+    contextLength: 2e5,
+    capabilities: CHAT_CAPS
+  },
+  "claude-3-5-sonnet": {
+    key: "claude-3-5-sonnet",
+    contextLength: 2e5,
+    capabilities: CHAT_CAPS
+  },
+  "claude-3-5-haiku": {
+    key: "claude-3-5-haiku",
+    contextLength: 2e5,
+    capabilities: CHAT_CAPS
+  },
+  "claude-3-opus": {
+    key: "claude-3-opus",
+    contextLength: 2e5,
+    capabilities: CHAT_CAPS
+  },
+  "claude-3-sonnet": {
+    key: "claude-3-sonnet",
+    contextLength: 2e5,
+    capabilities: CHAT_CAPS
+  },
+  "claude-3-haiku": {
+    key: "claude-3-haiku",
+    contextLength: 2e5,
+    capabilities: CHAT_CAPS
+  },
+  // --- Gemini (catalog: gemini-3.1-flash-lite, gemini-2.5-flash, auto-gemini-3) ---
+  "gemini-3.1-flash-lite": {
+    key: "gemini-3.1-flash-lite",
+    contextLength: 1048576,
+    capabilities: CHAT_CAPS
+  },
+  "gemini-3.1-pro": {
+    key: "gemini-3.1-pro",
+    contextLength: 1048576,
+    capabilities: CHAT_CAPS
+  },
+  "gemini-3-pro": {
+    key: "gemini-3-pro",
+    contextLength: 2097152,
+    capabilities: CHAT_CAPS
+  },
+  "auto-gemini-3": {
+    key: "auto-gemini-3",
+    contextLength: 1048576,
+    capabilities: CHAT_CAPS
+  },
+  "gemini-2.5-flash": {
+    key: "gemini-2.5-flash",
+    contextLength: 1048576,
+    capabilities: CHAT_CAPS
+  },
+  "gemini-2.5-pro": {
+    key: "gemini-2.5-pro",
+    contextLength: 2097152,
+    capabilities: CHAT_CAPS
+  },
+  "gemini-2.0-flash": {
+    key: "gemini-2.0-flash",
+    contextLength: 1048576,
+    capabilities: CHAT_CAPS
+  },
+  "gemini-1.5-flash": {
+    key: "gemini-1.5-flash",
+    contextLength: 1048576,
+    capabilities: CHAT_CAPS
+  },
+  "gemini-1.5-pro": {
+    key: "gemini-1.5-pro",
+    contextLength: 2097152,
+    capabilities: CHAT_CAPS
+  },
+  // --- Capability-only entries (F-D4-2-1, TASK-036 WP2): no documented context window — do NOT
+  // invent one. None of these are vision- or tool-capable chat models. ---
+  "text-embedding-3-small": {
+    key: "text-embedding-3-small",
+    capabilities: { vision: false, tools: false }
+  },
+  "text-embedding-3-large": {
+    key: "text-embedding-3-large",
+    capabilities: { vision: false, tools: false }
+  },
+  "text-embedding-ada-002": {
+    key: "text-embedding-ada-002",
+    capabilities: { vision: false, tools: false }
+  },
+  "whisper-1": {
+    key: "whisper-1",
+    capabilities: { vision: false, tools: false }
+  },
+  "tts-1": {
+    key: "tts-1",
+    capabilities: { vision: false, tools: false }
+  },
+  "tts-1-hd": {
+    key: "tts-1-hd",
+    capabilities: { vision: false, tools: false }
+  },
+  "dall-e-3": {
+    key: "dall-e-3",
+    capabilities: { vision: false, tools: false }
+  },
+  "gpt-image-1": {
+    key: "gpt-image-1",
+    capabilities: { vision: false, tools: false }
+  }
+};
+var REASONING_EFFORT_SUFFIXES = /* @__PURE__ */ new Set([
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh"
+]);
+function normalizeModelKey(model) {
+  let key = model.trim().toLowerCase();
+  const lastSlashIndex = key.lastIndexOf("/");
+  if (lastSlashIndex > 0 && lastSlashIndex < key.length - 1) {
+    const tail = key.slice(lastSlashIndex + 1);
+    if (REASONING_EFFORT_SUFFIXES.has(tail)) {
+      key = key.slice(0, lastSlashIndex);
+    }
+  }
+  const slashIndex = key.indexOf("/");
+  if (slashIndex > 0) {
+    key = key.slice(slashIndex + 1);
+  }
+  key = key.replace(/:(?:free|beta)$/i, "");
+  return key.trim();
+}
+var MIN_SUBSTRING_MATCH_KEY_LENGTH = 4;
+function lookupModelRef(model) {
+  const normalized = normalizeModelKey(model);
+  if (!normalized) {
+    return void 0;
+  }
+  const exact = MODEL_REFERENCE[normalized];
+  if (exact) {
+    return exact;
+  }
+  let prefixWinner;
+  for (const [key, entry] of Object.entries(MODEL_REFERENCE)) {
+    if (normalized.startsWith(key)) {
+      if (!prefixWinner || key.length > prefixWinner.key.length) {
+        prefixWinner = entry;
+      }
+    }
+  }
+  if (prefixWinner) {
+    return prefixWinner;
+  }
+  let substringWinner;
+  for (const [key, entry] of Object.entries(MODEL_REFERENCE)) {
+    if (key.length >= MIN_SUBSTRING_MATCH_KEY_LENGTH && normalized.includes(key)) {
+      if (!substringWinner || key.length > substringWinner.key.length) {
+        substringWinner = entry;
+      }
+    }
+  }
+  return substringWinner;
+}
+function lookupModelCapabilities(model) {
+  const normalized = normalizeModelKey(model);
+  if (!normalized) {
+    return void 0;
+  }
+  return MODEL_REFERENCE[normalized]?.capabilities;
+}
+function downgradeCapability(routeValue, hint) {
+  return hint === false ? false : routeValue;
+}
+function isUsableContextLength(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function extractModelContextLength(raw) {
+  if (!raw || typeof raw !== "object") {
+    return void 0;
+  }
+  const record = raw;
+  if (isUsableContextLength(record.context_length)) {
+    return record.context_length;
+  }
+  if (isUsableContextLength(record.max_model_len)) {
+    return record.max_model_len;
+  }
+  if (isUsableContextLength(record.context_window)) {
+    return record.context_window;
+  }
+  const topProvider = record.top_provider;
+  if (topProvider && typeof topProvider === "object") {
+    const nested = topProvider.context_length;
+    if (isUsableContextLength(nested)) {
+      return nested;
+    }
+  }
+  return void 0;
+}
+function asPricingNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return void 0;
+}
+function parseModelPricing(raw) {
+  if (!raw || typeof raw !== "object") {
+    return void 0;
+  }
+  const pricing = raw.pricing;
+  if (!pricing || typeof pricing !== "object") {
+    return void 0;
+  }
+  const record = pricing;
+  const prompt = asPricingNumber(record.prompt);
+  const completion = asPricingNumber(record.completion);
+  const request = asPricingNumber(record.request);
+  const image = asPricingNumber(record.image);
+  const currency = typeof record.currency === "string" ? record.currency : void 0;
+  const result = {
+    ...prompt !== void 0 ? { prompt } : {},
+    ...completion !== void 0 ? { completion } : {},
+    ...request !== void 0 ? { request } : {},
+    ...image !== void 0 ? { image } : {},
+    ...currency !== void 0 ? { currency } : {}
+  };
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+function detectModelFree(modelId, pricing, raw) {
+  if (/:free$/i.test(modelId.trim())) {
+    return true;
+  }
+  const effectivePricing = pricing ?? parseModelPricing(raw);
+  if (!effectivePricing) {
+    return false;
+  }
+  const components = [
+    effectivePricing.prompt,
+    effectivePricing.completion,
+    effectivePricing.request,
+    effectivePricing.image
+  ].filter((value) => typeof value === "number");
+  if (components.length === 0) {
+    return false;
+  }
+  return components.every((value) => value === 0);
+}
+function resolveModelContextWindow(input) {
+  if (isUsableContextLength(input.discovered)) {
+    return { contextWindow: input.discovered, source: "discovered" };
+  }
+  if (isUsableContextLength(input.reference)) {
+    return { contextWindow: input.reference, source: "reference" };
+  }
+  if (isUsableContextLength(input.configured)) {
+    return { contextWindow: input.configured, source: "configured" };
+  }
+  const fallback = isUsableContextLength(input.defaultContextWindow) ? input.defaultContextWindow : DEFAULT_CONTEXT_WINDOW;
+  return { contextWindow: fallback, source: "default" };
+}
+function fillConfiguredContextLength(route, models) {
+  if (!isUsableContextLength(route.contextWindow)) {
+    return models;
+  }
+  const configured = route.contextWindow;
+  return models.map((entry) => {
+    if (isUsableContextLength(entry.contextLength)) {
+      return entry;
+    }
+    if (route.model !== void 0 && entry.modelId !== route.model) {
+      return entry;
+    }
+    return {
+      ...entry,
+      contextLength: configured,
+      // FT-002: typed provenance (canonical) + metadata alias (back-compat).
+      contextWindowSource: "configured",
+      metadata: { ...entry.metadata ?? {}, contextWindowSource: "configured" }
+    };
+  });
+}
+function modelContextCacheKey(input) {
+  if (typeof input === "string") {
+    return { key: `::${input}`, model: input };
+  }
+  const scope = input.baseUrl ?? input.transportId ?? "";
+  return { key: `${scope}::${input.model}`, model: input.model };
+}
+
 // src/config.ts
 var DEFAULT_OPERATIONS = ["text", "image", "file"];
 var DEFAULT_STRATEGY = "priority";
@@ -303,16 +670,26 @@ var DEFAULT_RETRY_DELAY_MS = {
 function slugify(value) {
   return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function toPublicCapabilities(capabilities) {
+function toPublicCapabilities(capabilities, model) {
+  const hints = model ? lookupModelCapabilities(model) : void 0;
   return {
     browserSafe: capabilities.browserSafe,
     supportsStreaming: capabilities.supportsStreaming,
-    supportsToolSchema: capabilities.supportsToolSchema,
+    supportsToolSchema: downgradeCapability(
+      capabilities.supportsToolSchema,
+      hints?.tools
+    ),
     supportsToolExecution: capabilities.supportsToolExecution,
-    supportsClientToolExecution: capabilities.supportsClientToolExecution,
+    supportsClientToolExecution: downgradeCapability(
+      capabilities.supportsClientToolExecution,
+      hints?.tools
+    ),
     supportsFileUpload: capabilities.supportsFileUpload,
     supportsFileOutput: capabilities.supportsFileOutput,
-    supportsImageInput: capabilities.supportsImageInput,
+    supportsImageInput: downgradeCapability(
+      capabilities.supportsImageInput,
+      hints?.vision
+    ),
     supportsImageOutput: capabilities.supportsImageOutput
   };
 }
@@ -713,7 +1090,13 @@ function defaultCapabilities(transport, runtime) {
     supportsStreaming: transport.kind === "api" || transport.kind === "acp",
     supportsToolSchema: transport.kind === "api",
     supportsToolExecution: transport.kind === "acp",
-    supportsClientToolExecution: transport.kind === "api",
+    // TASK-036 D5/WP3+WP4: acp runs client tools through the in-process MCP
+    // bridge (session/new.mcpServers → ai-connect-client-tools); cli/server run
+    // them through the shared text-protocol round (client-tools-text-protocol.ts:
+    // preamble + non-live echo history + trailing-fence extraction) landed in
+    // the same diff as this flag. The per-account `capabilities` override
+    // remains the escape hatch in both directions.
+    supportsClientToolExecution: transport.kind === "api" || transport.kind === "acp" || transport.kind === "cli" || transport.kind === "server",
     // C6 / F-P-4: api routes now advertise document + image input parity with acp.
     // The per-account `capabilities` override remains the escape hatch for
     // text-only api proxies that must opt out. REQ-024: a cli route advertises
@@ -1836,7 +2219,7 @@ function runtimeEligible(route, runtime) {
   }
   return route.runtime === runtime.kind;
 }
-function capabilityMatch(route, hints) {
+function capabilityMatch(capabilities, hints) {
   if (!hints?.requiredCapabilities) {
     return true;
   }
@@ -1844,9 +2227,33 @@ function capabilityMatch(route, hints) {
     if (value === void 0) {
       return true;
     }
-    return route.capabilities[key] === value;
+    return capabilities[key] === value;
   });
 }
+function effectiveCapabilitiesForModel(route, requestedModel) {
+  if (!requestedModel) {
+    return route.capabilities;
+  }
+  const hints = lookupModelCapabilities(requestedModel);
+  if (!hints) {
+    return route.capabilities;
+  }
+  return {
+    ...route.capabilities,
+    supportsToolSchema: downgradeCapability(
+      route.capabilities.supportsToolSchema,
+      hints.tools
+    ),
+    supportsClientToolExecution: downgradeCapability(
+      route.capabilities.supportsClientToolExecution,
+      hints.tools
+    ),
+    supportsImageInput: downgradeCapability(
+      route.capabilities.supportsImageInput,
+      hints.vision
+    )
+  };
+}
 function preferredProviderScore(route, preferredProviders) {
   if (!preferredProviders || preferredProviders.length === 0) {
     return Number.MAX_SAFE_INTEGER;
@@ -1954,16 +2361,29 @@ var RouteRegistry = class {
     ).filter((route) => runtimeEligible(route, this.runtime)).filter((route) => {
       const state = this.getHealth(route).state;
       return state !== "cooling_down" && state !== "unavailable";
-    }).map((route) => ({
-      model: route.model,
-      provider: route.provider,
-      routeId: route.id,
-      transportKind: route.transport.kind,
-      // INV-PROJ-1: project the secret-free subset (never the full
-      // RouteCapabilities) so internal routing flags do not leak to the
-      // ModelSelector / listCandidateModels surface (#12).
-      capabilities: toPublicCapabilities(route.capabilities)
-    }));
+    }).flatMap((route) => {
+      if (route.advertisedModels.length === 0) {
+        return [
+          {
+            model: route.model,
+            provider: route.provider,
+            routeId: route.id,
+            transportKind: route.transport.kind,
+            // INV-PROJ-1: project the secret-free subset (never the full
+            // RouteCapabilities) so internal routing flags do not leak to the
+            // ModelSelector / listCandidateModels surface (#12).
+            capabilities: toPublicCapabilities(route.capabilities)
+          }
+        ];
+      }
+      return route.advertisedModels.map((model) => ({
+        model,
+        provider: route.provider,
+        routeId: route.id,
+        transportKind: route.transport.kind,
+        capabilities: toPublicCapabilities(route.capabilities, model)
+      }));
+    });
   }
   resolveCandidates(request) {
     const operation = request.operation;
@@ -1971,7 +2391,12 @@ var RouteRegistry = class {
     const routeIds = request.routeHints?.pool?.length ? resolveRouteSelectors(request.routeHints.pool, this.config.routes) : operationRouting.pool;
     const excludedIds = new Set(request.routeHints?.excludeRouteIds ?? []);
     const requestedModel = request.routeHints?.model;
-    const eligible = routeIds.map((routeId) => this.#routeMap.get(routeId)).filter((route) => Boolean(route)).filter((route) => !excludedIds.has(route.id)).filter((route) => runtimeEligible(route, this.runtime)).filter((route) => capabilityMatch(route, request.routeHints)).map((route) => applyRequestedModel(route, requestedModel)).filter((route) => Boolean(route));
+    const eligible = routeIds.map((routeId) => this.#routeMap.get(routeId)).filter((route) => Boolean(route)).filter((route) => !excludedIds.has(route.id)).filter((route) => runtimeEligible(route, this.runtime)).filter(
+      (route) => capabilityMatch(
+        effectiveCapabilitiesForModel(route, requestedModel),
+        request.routeHints
+      )
+    ).map((route) => applyRequestedModel(route, requestedModel)).filter((route) => Boolean(route));
     const strategy = request.routeHints?.strategy ?? operationRouting.strategy;
     const cursorKey = `${operation}:${strategy}:${eligible.map((route) => route.id).join("|")}`;
     const healthyIds = new Set(
@@ -2086,223 +2511,6 @@ function applyRequestedModel(route, requestedModel) {
   return { ...route, model: requestedModel };
 }
 
-// src/model-reference.ts
-var DEFAULT_CONTEXT_WINDOW = 8192;
-var MODEL_REFERENCE = {
-  // --- OpenAI (gpt / codex families; catalog: gpt-4.1, gpt-5.4/xhigh) ---
-  "gpt-4.1": { key: "gpt-4.1", contextLength: 1047576 },
-  "gpt-4.1-mini": { key: "gpt-4.1-mini", contextLength: 1047576 },
-  "gpt-4.1-nano": { key: "gpt-4.1-nano", contextLength: 1047576 },
-  "gpt-4o": { key: "gpt-4o", contextLength: 128e3 },
-  "gpt-4o-mini": { key: "gpt-4o-mini", contextLength: 128e3 },
-  "gpt-4-turbo": { key: "gpt-4-turbo", contextLength: 128e3 },
-  "gpt-4": { key: "gpt-4", contextLength: 8192 },
-  "gpt-3.5-turbo": { key: "gpt-3.5-turbo", contextLength: 16385 },
-  "gpt-5": { key: "gpt-5", contextLength: 4e5 },
-  "gpt-5.4": { key: "gpt-5.4", contextLength: 4e5 },
-  o1: { key: "o1", contextLength: 2e5 },
-  "o1-mini": { key: "o1-mini", contextLength: 128e3 },
-  "o3-mini": { key: "o3-mini", contextLength: 2e5 },
-  // --- Anthropic (claude families; catalog: claude-sonnet-4-6, claude-sonnet-4) ---
-  "claude-sonnet-4-6": { key: "claude-sonnet-4-6", contextLength: 2e5 },
-  "claude-sonnet-4": { key: "claude-sonnet-4", contextLength: 2e5 },
-  "claude-opus-4": { key: "claude-opus-4", contextLength: 2e5 },
-  "claude-haiku-4": { key: "claude-haiku-4", contextLength: 2e5 },
-  "claude-3-5-sonnet": { key: "claude-3-5-sonnet", contextLength: 2e5 },
-  "claude-3-5-haiku": { key: "claude-3-5-haiku", contextLength: 2e5 },
-  "claude-3-opus": { key: "claude-3-opus", contextLength: 2e5 },
-  "claude-3-sonnet": { key: "claude-3-sonnet", contextLength: 2e5 },
-  "claude-3-haiku": { key: "claude-3-haiku", contextLength: 2e5 },
-  // --- Gemini (catalog: gemini-3.1-flash-lite, gemini-2.5-flash, auto-gemini-3) ---
-  "gemini-3.1-flash-lite": {
-    key: "gemini-3.1-flash-lite",
-    contextLength: 1048576
-  },
-  "gemini-3.1-pro": { key: "gemini-3.1-pro", contextLength: 1048576 },
-  "gemini-3-pro": { key: "gemini-3-pro", contextLength: 2097152 },
-  "auto-gemini-3": { key: "auto-gemini-3", contextLength: 1048576 },
-  "gemini-2.5-flash": { key: "gemini-2.5-flash", contextLength: 1048576 },
-  "gemini-2.5-pro": { key: "gemini-2.5-pro", contextLength: 2097152 },
-  "gemini-2.0-flash": { key: "gemini-2.0-flash", contextLength: 1048576 },
-  "gemini-1.5-flash": { key: "gemini-1.5-flash", contextLength: 1048576 },
-  "gemini-1.5-pro": { key: "gemini-1.5-pro", contextLength: 2097152 }
-};
-var REASONING_EFFORT_SUFFIXES = /* @__PURE__ */ new Set([
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh"
-]);
-function normalizeModelKey(model) {
-  let key = model.trim().toLowerCase();
-  const lastSlashIndex = key.lastIndexOf("/");
-  if (lastSlashIndex > 0 && lastSlashIndex < key.length - 1) {
-    const tail = key.slice(lastSlashIndex + 1);
-    if (REASONING_EFFORT_SUFFIXES.has(tail)) {
-      key = key.slice(0, lastSlashIndex);
-    }
-  }
-  const slashIndex = key.indexOf("/");
-  if (slashIndex > 0) {
-    key = key.slice(slashIndex + 1);
-  }
-  key = key.replace(/:(?:free|beta)$/i, "");
-  return key.trim();
-}
-var MIN_SUBSTRING_MATCH_KEY_LENGTH = 4;
-function lookupModelRef(model) {
-  const normalized = normalizeModelKey(model);
-  if (!normalized) {
-    return void 0;
-  }
-  const exact = MODEL_REFERENCE[normalized];
-  if (exact) {
-    return exact;
-  }
-  let prefixWinner;
-  for (const [key, entry] of Object.entries(MODEL_REFERENCE)) {
-    if (normalized.startsWith(key)) {
-      if (!prefixWinner || key.length > prefixWinner.key.length) {
-        prefixWinner = entry;
-      }
-    }
-  }
-  if (prefixWinner) {
-    return prefixWinner;
-  }
-  let substringWinner;
-  for (const [key, entry] of Object.entries(MODEL_REFERENCE)) {
-    if (key.length >= MIN_SUBSTRING_MATCH_KEY_LENGTH && normalized.includes(key)) {
-      if (!substringWinner || key.length > substringWinner.key.length) {
-        substringWinner = entry;
-      }
-    }
-  }
-  return substringWinner;
-}
-function isUsableContextLength(value) {
-  return typeof value === "number" && Number.isFinite(value) && value > 0;
-}
-function extractModelContextLength(raw) {
-  if (!raw || typeof raw !== "object") {
-    return void 0;
-  }
-  const record = raw;
-  if (isUsableContextLength(record.context_length)) {
-    return record.context_length;
-  }
-  if (isUsableContextLength(record.max_model_len)) {
-    return record.max_model_len;
-  }
-  if (isUsableContextLength(record.context_window)) {
-    return record.context_window;
-  }
-  const topProvider = record.top_provider;
-  if (topProvider && typeof topProvider === "object") {
-    const nested = topProvider.context_length;
-    if (isUsableContextLength(nested)) {
-      return nested;
-    }
-  }
-  return void 0;
-}
-function asPricingNumber(value) {
-  if (typeof value === "number" && Number.isFinite(value)) {
-    return value;
-  }
-  if (typeof value === "string" && value.trim().length > 0) {
-    const parsed = Number(value);
-    if (Number.isFinite(parsed)) {
-      return parsed;
-    }
-  }
-  return void 0;
-}
-function parseModelPricing(raw) {
-  if (!raw || typeof raw !== "object") {
-    return void 0;
-  }
-  const pricing = raw.pricing;
-  if (!pricing || typeof pricing !== "object") {
-    return void 0;
-  }
-  const record = pricing;
-  const prompt = asPricingNumber(record.prompt);
-  const completion = asPricingNumber(record.completion);
-  const request = asPricingNumber(record.request);
-  const image = asPricingNumber(record.image);
-  const currency = typeof record.currency === "string" ? record.currency : void 0;
-  const result = {
-    ...prompt !== void 0 ? { prompt } : {},
-    ...completion !== void 0 ? { completion } : {},
-    ...request !== void 0 ? { request } : {},
-    ...image !== void 0 ? { image } : {},
-    ...currency !== void 0 ? { currency } : {}
-  };
-  return Object.keys(result).length > 0 ? result : void 0;
-}
-function detectModelFree(modelId, pricing, raw) {
-  if (/:free$/i.test(modelId.trim())) {
-    return true;
-  }
-  const effectivePricing = pricing ?? parseModelPricing(raw);
-  if (!effectivePricing) {
-    return false;
-  }
-  const components = [
-    effectivePricing.prompt,
-    effectivePricing.completion,
-    effectivePricing.request,
-    effectivePricing.image
-  ].filter((value) => typeof value === "number");
-  if (components.length === 0) {
-    return false;
-  }
-  return components.every((value) => value === 0);
-}
-function resolveModelContextWindow(input) {
-  if (isUsableContextLength(input.discovered)) {
-    return { contextWindow: input.discovered, source: "discovered" };
-  }
-  if (isUsableContextLength(input.reference)) {
-    return { contextWindow: input.reference, source: "reference" };
-  }
-  if (isUsableContextLength(input.configured)) {
-    return { contextWindow: input.configured, source: "configured" };
-  }
-  const fallback = isUsableContextLength(input.defaultContextWindow) ? input.defaultContextWindow : DEFAULT_CONTEXT_WINDOW;
-  return { contextWindow: fallback, source: "default" };
-}
-function fillConfiguredContextLength(route, models) {
-  if (!isUsableContextLength(route.contextWindow)) {
-    return models;
-  }
-  const configured = route.contextWindow;
-  return models.map((entry) => {
-    if (isUsableContextLength(entry.contextLength)) {
-      return entry;
-    }
-    if (route.model !== void 0 && entry.modelId !== route.model) {
-      return entry;
-    }
-    return {
-      ...entry,
-      contextLength: configured,
-      // FT-002: typed provenance (canonical) + metadata alias (back-compat).
-      contextWindowSource: "configured",
-      metadata: { ...entry.metadata ?? {}, contextWindowSource: "configured" }
-    };
-  });
-}
-function modelContextCacheKey(input) {
-  if (typeof input === "string") {
-    return { key: `::${input}`, model: input };
-  }
-  const scope = input.baseUrl ?? input.transportId ?? "";
-  return { key: `${scope}::${input.model}`, model: input.model };
-}
-
 // src/probe.ts
 var PROBE_DEFAULT_TIMEOUT_MS = 8e3;
 var PROBE_DEFAULT_TTL_MS = 3e5;
@@ -2744,8 +2952,14 @@ function mergeUsage(current, next) {
   return merged;
 }
 function requiresToolSchema(request) {
+  const clientToolNames = new Set(
+    (request.clientTools ?? []).map((tool) => tool.function.name)
+  );
+  const hasNativeTool = (request.parameters?.tools ?? []).some(
+    (tool) => !clientToolNames.has(tool.function.name)
+  );
   return Boolean(
-    request.parameters?.tools?.length || request.parameters?.toolChoice !== void 0 || request.parameters?.parallelToolCalls !== void 0
+    hasNativeTool || request.parameters?.toolChoice !== void 0 || request.parameters?.parallelToolCalls !== void 0
   );
 }
 function requiresImageInput(request) {
@@ -2849,6 +3063,14 @@ function applyRouteDefaults(route, request) {
 }
 function toPublicRoute(route, health) {
   const capabilities = toPublicCapabilities(route.capabilities);
+  const perModelCapabilities = {};
+  let hasModelCapabilityHints = false;
+  for (const model of route.advertisedModels) {
+    if (lookupModelCapabilities(model)) {
+      hasModelCapabilityHints = true;
+    }
+    perModelCapabilities[model] = toPublicCapabilities(route.capabilities, model);
+  }
   return {
     id: route.id,
     label: route.label ?? route.id,
@@ -2861,6 +3083,7 @@ function toPublicRoute(route, health) {
     ...route.defaultResponseFormat !== void 0 ? { defaultResponseFormat: route.defaultResponseFormat } : {},
     ...route.systemPrompt !== void 0 ? { systemPrompt: route.systemPrompt } : {},
     capabilities,
+    ...hasModelCapabilityHints ? { perModelCapabilities } : {},
     health
   };
 }
@@ -3262,10 +3485,10 @@ function createClient(configOrInput, options = {}) {
       request.clientTools,
       clientToolRegistry
     );
-    if (clientTools.length > 0 && (normalized.operation !== "text" || normalized.attachments.length > 0 || normalized.image !== void 0)) {
+    if (clientTools.length > 0 && normalized.operation !== "text") {
       throw new AiConnectError(
-        "validation_error",
-        "clientTools are currently supported only for text requests without attachments or image options."
+        "unsupported_capability",
+        `clientTools are not supported for operation "${normalized.operation}" \u2014 tool-loop semantics exist only for text requests.`
       );
     }
     const mergedTools = clientTools.length ? mergeToolDefinitions(normalized.parameters?.tools, clientTools) : void 0;
@@ -3385,12 +3608,15 @@ function createClient(configOrInput, options = {}) {
   async function executeGenerateOperation(normalizedRequest, operationName, abort, seed = {}) {
     const startedAt = seed.startMs ?? nowMs(runtime);
     const requestId = seed.requestId ?? resolveEventRequestId(normalizedRequest.logContext);
-    const { requiresImage, requiresFile, request: capabilityScopedRequest } = resolveRequiredCapabilities(normalizedRequest);
+    const { requiresImage, requiresFile, requiresClientTools, request: capabilityScopedRequest } = resolveRequiredCapabilities(normalizedRequest);
     const resolvedCandidates = router.resolveCandidates(capabilityScopedRequest);
     const candidates = seed.candidates ?? resolvedCandidates.map(summarizeRoute);
     const requestSummary = summarizeRequest(normalizedRequest, candidates);
     if (resolvedCandidates.length === 0) {
-      const error = requiresImage || requiresFile ? new AiConnectError(
+      const error = requiresClientTools ? new AiConnectError(
+        "unsupported_capability",
+        `No route supports the requested capabilities: client tool execution${requiresImage ? ", image input" : ""}${requiresFile ? ", file upload" : ""}.`
+      ) : requiresImage || requiresFile ? new AiConnectError(
         "unsupported_capability",
         `No eligible route supports the required ${requiresFile ? "document/file" : "image"} input for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`
       ) : new AiConnectError("not_supported", `No eligible routes are available for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`);
@@ -4452,7 +4678,7 @@ function createClient(configOrInput, options = {}) {
         if (candidates.length === 0) {
           const error = requiresImage || requiresFile || requiresClientTools ? new AiConnectError(
             "unsupported_capability",
-            requiresImage || requiresFile ? `No eligible route supports the required ${requiresFile ? "document/file" : "image"} input for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".` : `No eligible route supports client-side tool execution for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`
+            requiresClientTools ? `No route supports the requested capabilities: client tool execution${requiresImage ? ", image input" : ""}${requiresFile ? ", file upload" : ""}.` : `No eligible route supports the required ${requiresFile ? "document/file" : "image"} input for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`
           ) : new AiConnectError("not_supported", `No eligible routes are available for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`);
           await emitWideEvent({
             timestamp: isoTimestamp(startedAt),
@@ -4618,6 +4844,17 @@ function createClient(configOrInput, options = {}) {
                   await returnIterator();
                 }
                 if (!roundResult) {
+                  if (toolRoundsExecuted > 0) {
+                    lastResult = {
+                      route,
+                      text: accumulatedText,
+                      attachments: [],
+                      warnings: [...aggregatedWarnings],
+                      attempts,
+                      ...aggregatedUsage ? { usage: aggregatedUsage } : {}
+                    };
+                    yield { type: "result", result: lastResult };
+                  }
                   break roundsLoop;
                 }
                 if (registry.size === 0 || !roundResult.toolCalls?.length) {
@@ -7404,10 +7641,12 @@ export {
   AI_CONNECT_DEFAULT_SERVER_COMMANDS,
   AI_CONNECT_DEFAULT_SERVER_PRESETS,
   AiConnectError,
+  ClientToolExecutionError,
   DEFAULT_CONTEXT_WINDOW,
   DEFAULT_IMAGE_SIZE,
   IMAGE_PROMPT_PROTOCOL,
   IMAGE_SIZE_PRESETS,
+  MAX_CLIENT_TOOL_LOOP_DEPTH,
   MODEL_REFERENCE,
   PROBE_DEFAULT_CONCURRENCY,
   PROBE_DEFAULT_TIMEOUT_MS,
@@ -7426,6 +7665,7 @@ export {
   createRuntimeEnvironment,
   defineConfig,
   detectModelFree,
+  downgradeCapability,
   extractImagePayloads,
   extractModelContextLength,
   filterStructuralMarkers,
@@ -7439,6 +7679,7 @@ export {
   isNormalizedConfig,
   isPortableDocumentFile,
   listTextProviderCatalog,
+  lookupModelCapabilities,
   lookupModelRef,
   mapAbortError,
   materializePortableFile,