@vedmalex/ai-connect 0.8.0 → 0.10.0

package/dist/browser/index.js

@@ -12,7 +12,10 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
       // pi takes file/image attachments as separate `@<path>` argv tokens (REQ-024);
       // {files} expands one `@<staged-path>` token per attachment. pi stages all
       // categories (PDFs as-is, no extraction guarantee).
-      argsTemplate: ["--print", "--model", "{model}", "{files}", "{prompt}"],
+      // H10 (flag injection): the `--` end-of-options token precedes {files}/{prompt}
+      // — both are BARE positionals here — so an `@<path>` reference or a prompt that
+      // starts with `-` is parsed by pi as a positional, never as a flag.
+      argsTemplate: ["--print", "--model", "{model}", "--", "{files}", "{prompt}"],
       discovery: {
         via: "none"
       },
@@ -32,13 +35,22 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
     transportId: "claude-cli",
     options: {
       preset: "claude",
-      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "{prompt}"],
+      // H10 (flag injection): `--` precedes the trailing {prompt} positional so a
+      // prompt starting with `-` (e.g. "--dangerously-skip-permissions") is parsed
+      // by the claude CLI as a positional, not a flag.
+      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "--", "{prompt}"],
       discovery: {
         via: "acp",
         acp: {
           transportId: "claude-code-acp"
         }
       },
+      // SENTINEL (documentation-only): the `__preset__:*` textPath/errorPath values
+      // are NOT resolved as live JSON paths. This `parser` block records which
+      // dedicated parser a built-in preset maps to (parseClaudeCli); dispatch for a
+      // preset route goes through the `cliOptions.preset` switch in cli.ts
+      // (parseCliResult), which only reads a parser config when a ROUTE sets its own
+      // `cli.parser`. See the mirrored note in cli.ts::parseCliResult.
       parser: {
         kind: "json",
         textPath: "__preset__:claude.result",
@@ -54,7 +66,11 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
     transportId: "openclaude-cli",
     options: {
       preset: "openclaude",
-      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "{prompt}"],
+      // H10 (flag injection): `--` precedes the trailing {prompt} positional (see
+      // the claude preset above for rationale).
+      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "--", "{prompt}"],
+      // SENTINEL (documentation-only): see the claude preset note — `__preset__:*`
+      // paths are markers, not live JSON paths; dispatch is via the preset switch.
       parser: {
         kind: "json",
         textPath: "__preset__:claude.result",
@@ -73,6 +89,11 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
       // codex exec takes image attachments via `-i/--image <FILE>` flags
       // (REQ-024); {files} expands a `--image <staged-path>` pair per image.
       // Images only — a non-image attachment cleanly rejects pre-spawn.
+      // H10 (flag injection): `--` sits AFTER {files} and before the trailing
+      // {prompt} positional. Unlike pi, codex files are passed via the explicit
+      // `--image <path>` flag (the path is that flag's VALUE, not a positional), so
+      // `--` must NOT precede {files} or it would neutralize `--image`. It guards
+      // only the {prompt} positional against being parsed as a flag.
       argsTemplate: [
         "exec",
         "--json",
@@ -81,6 +102,7 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
         "--model",
         "{model}",
         "{files}",
+        "--",
         "{prompt}"
       ],
       discovery: {
@@ -94,6 +116,11 @@ var AI_CONNECT_DEFAULT_CLI_PRESETS = {
         perFileArgs: ["--image", "{path}"],
         categories: ["image"]
       },
+      // SENTINEL (documentation-only): the `__preset__:*` path values below are
+      // markers naming the dedicated parser this preset maps to (parseCodexCli), NOT
+      // live JSONL selectors. Dispatch for a preset route runs through the
+      // `cliOptions.preset` switch in cli.ts::parseCliResult; this block is only ever
+      // read as a live parser when a ROUTE overrides `cli.parser`.
       parser: {
         kind: "jsonl",
         text: {
@@ -130,6 +157,19 @@ var AiConnectError = class extends Error {
     this.code = code;
     this.details = details;
   }
+  /**
+   * `Error.prototype.message` is non-enumerable, so a bare `JSON.stringify(err)` silently drops
+   * it (LOW, review-report-seed.md). Provide an explicit projection so serializing an
+   * `AiConnectError` (logs, wide events, error-response bodies) always carries the message.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details
+    };
+  }
 };
 function isAiConnectError(error) {
   return error instanceof AiConnectError;
@@ -160,6 +200,16 @@ function toAiConnectError(error, fallbackCode = "temporary_unavailable") {
 // src/config.ts
 var DEFAULT_OPERATIONS = ["text", "image", "file"];
 var DEFAULT_STRATEGY = "priority";
+var CLI_TRANSPORT_ID_BY_PROVIDER = {
+  anthropic: "claude-cli",
+  openclaude: "openclaude-cli",
+  openai: "codex-cli",
+  pi: "pi-cli"
+};
+var ACP_TRANSPORT_ID_BY_PROVIDER = {
+  anthropic: "claude-code-acp",
+  openai: "codex-acp"
+};
 var DEFAULT_FALLBACK_ACTIONS = {
   rate_limit: [
     "rotate-credential",
@@ -271,33 +321,64 @@ function assert(condition, message) {
     throw new AiConnectError("validation_error", message);
   }
 }
-function asPositiveInteger(value, fallback) {
+function asPositiveInteger(value, fallback, fieldLabel) {
+  if (value === void 0) {
+    return fallback;
+  }
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    if (fieldLabel) {
+      console.warn(
+        `[ai-connect] ${fieldLabel} must be a positive finite number when provided; received ${JSON.stringify(value)}. Falling back to ${fallback}.`
+      );
+    }
     return fallback;
   }
   return Math.floor(value);
 }
-function asNonNegativeInteger(value, fallback) {
+function asNonNegativeInteger(value, fallback, fieldLabel) {
+  if (value === void 0) {
+    return fallback;
+  }
   if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    if (fieldLabel) {
+      console.warn(
+        `[ai-connect] ${fieldLabel} must be a non-negative finite number when provided; received ${JSON.stringify(value)}. Falling back to ${fallback}.`
+      );
+    }
     return fallback;
   }
   return Math.floor(value);
 }
-function asOptionalContextWindow(value) {
+function asOptionalContextWindow(value, fieldLabel) {
+  if (value === void 0) {
+    return void 0;
+  }
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    if (fieldLabel) {
+      console.warn(
+        `[ai-connect] ${fieldLabel} must be a positive finite number when provided; received ${JSON.stringify(value)}. Ignoring.`
+      );
+    }
     return void 0;
   }
   return Math.floor(value);
 }
-function normalizeModelInput(input, accountContextWindow) {
+function normalizeModelInput(input, accountContextWindow, accountId, providerId) {
   if (typeof input === "string") {
     return {
       id: input.trim(),
       ...accountContextWindow !== void 0 ? { contextWindow: accountContextWindow } : {}
     };
   }
+  assert(
+    typeof input.id === "string" && input.id.trim().length > 0,
+    `Account "${accountId}" for provider "${providerId}" declared a model entry with a missing or empty "id".`
+  );
   const id = input.id.trim();
-  const override = asOptionalContextWindow(input.contextWindow);
+  const override = asOptionalContextWindow(
+    input.contextWindow,
+    `Model "${id}" (account "${accountId}", provider "${providerId}") contextWindow`
+  );
   const contextWindow = override ?? accountContextWindow;
   return {
     id,
@@ -308,7 +389,8 @@ function asFanoutBound(value) {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
     return Number.POSITIVE_INFINITY;
   }
-  return Math.floor(value);
+  const floored = Math.floor(value);
+  return floored <= 0 ? Number.POSITIVE_INFINITY : floored;
 }
 function normalizeFanoutPolicy(policy) {
   return {
@@ -534,7 +616,7 @@ function normalizeTransport(providerId, input) {
     };
   }
   if (descriptor.kind === "cli") {
-    const inferredId2 = providerId === "anthropic" ? "claude-cli" : providerId === "openclaude" ? "openclaude-cli" : providerId === "openai" ? "codex-cli" : providerId === "pi" ? "pi-cli" : "cli";
+    const inferredId2 = CLI_TRANSPORT_ID_BY_PROVIDER[providerId] ?? "cli";
     return {
       kind: "cli",
       id: descriptor.id?.trim() || inferredId2,
@@ -551,7 +633,7 @@ function normalizeTransport(providerId, input) {
       ...descriptor.baseUrl?.trim() ? { baseUrl: descriptor.baseUrl.trim() } : {}
     };
   }
-  const inferredId = providerId === "anthropic" ? "claude-code-acp" : providerId === "openai" ? "codex-acp" : "acp";
+  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";
@@ -648,20 +730,26 @@ function defaultCapabilities(transport, runtime) {
 }
 function normalizeCredential(providerId, accountId, transport, input, index) {
   const id = input.id?.trim() || `${accountId}-credential-${index + 1}`;
-  const source = input.source?.trim() || (input.apiKey ? "literal" : input.apiKeyEnv ? "env" : transport.kind === "api" ? "env" : "session");
+  const trimmedApiKey = input.apiKey?.trim();
+  const trimmedApiKeyEnv = input.apiKeyEnv?.trim();
+  const source = input.source?.trim() || (trimmedApiKey ? "literal" : trimmedApiKeyEnv ? "env" : transport.kind === "api" ? "env" : "session");
   if (transport.kind === "api") {
     assert(
-      Boolean(input.apiKey?.trim()) || Boolean(input.apiKeyEnv?.trim()),
+      Boolean(trimmedApiKey) || Boolean(trimmedApiKeyEnv),
       `API account "${accountId}" for provider "${providerId}" requires apiKey or apiKeyEnv credentials.`
     );
   }
   return {
     id,
     source,
-    weight: asPositiveInteger(input.weight, 1),
+    weight: asPositiveInteger(
+      input.weight,
+      1,
+      `Credential "${id}" (account "${accountId}", provider "${providerId}") weight`
+    ),
     metadata: input.metadata ?? {},
-    ...input.apiKey?.trim() ? { apiKey: input.apiKey.trim() } : {},
-    ...input.apiKeyEnv?.trim() ? { apiKeyEnv: input.apiKeyEnv.trim() } : {},
+    ...trimmedApiKey ? { apiKey: trimmedApiKey } : {},
+    ...trimmedApiKeyEnv ? { apiKeyEnv: trimmedApiKeyEnv } : {},
     ...input.apiKeyDelimiter ? { apiKeyDelimiter: input.apiKeyDelimiter } : {}
   };
 }
@@ -695,6 +783,31 @@ function buildRouteId(route) {
     slugify(route.model)
   ].join(":");
 }
+function assertRouteIdUniqueness(routes) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const group = byId.get(route.id);
+    if (group) {
+      group.push(route);
+    } else {
+      byId.set(route.id, [route]);
+    }
+  }
+  for (const [id, group] of byId) {
+    if (group.length <= 1) {
+      continue;
+    }
+    const distinctModels = [...new Set(group.map((route) => route.model))];
+    if (distinctModels.length <= 1) {
+      continue;
+    }
+    const first = group[0];
+    assert(
+      false,
+      `Route id "${id}" is ambiguous: model(s) ${distinctModels.map((model) => `"${model}"`).join(", ")} on account "${first.accountId}" (provider "${first.provider}") slugify to the same route id. Rename one of the models so they no longer collide after slugification.`
+    );
+  }
+}
 function routeAliases(route) {
   return [
     route.provider,
@@ -819,7 +932,8 @@ function defineConfig(input) {
       const transport = normalizeTransport(providerId, accountInput.transport);
       const runtime = normalizeRuntime(transport, accountInput.runtime);
       const accountContextWindow = asOptionalContextWindow(
-        accountInput.contextWindow
+        accountInput.contextWindow,
+        `Account "${accountId}" (provider "${providerId}") contextWindow`
       );
       const accountModelAllowlistMode = accountInput.modelAllowlistMode ?? "strict";
       const accountContextMode = accountInput.contextMode ?? "workspace";
@@ -829,7 +943,9 @@ function defineConfig(input) {
         Array.isArray(accountInput.models) && accountInput.models.length > 0,
         `Account "${accountId}" for provider "${providerId}" must declare at least one model.`
       );
-      const models = accountInput.models.map((model) => normalizeModelInput(model, accountContextWindow)).filter((model) => model.id.length > 0);
+      const models = accountInput.models.map(
+        (model) => normalizeModelInput(model, accountContextWindow, accountId, providerId)
+      ).filter((model) => model.id.length > 0);
       assert(
         models.length > 0,
         `Account "${accountId}" for provider "${providerId}" must declare at least one model.`
@@ -859,8 +975,16 @@ function defineConfig(input) {
         credentials,
         capabilities,
         verify,
-        weight: asPositiveInteger(accountInput.weight, 1),
-        priority: asNonNegativeInteger(accountInput.priority, accountIndex),
+        weight: asPositiveInteger(
+          accountInput.weight,
+          1,
+          `Account "${accountId}" (provider "${providerId}") weight`
+        ),
+        priority: asNonNegativeInteger(
+          accountInput.priority,
+          accountIndex,
+          `Account "${accountId}" (provider "${providerId}") priority`
+        ),
         enabled: accountInput.enabled ?? true
       };
       accounts.push(normalizedAccount);
@@ -907,6 +1031,7 @@ function defineConfig(input) {
     };
   }
   assert(routes.length > 0, "At least one enabled route must be produced.");
+  assertRouteIdUniqueness(routes);
   finalizeRotationCapabilities(routes);
   const strategy = input.routing?.strategy ?? DEFAULT_STRATEGY;
   const resolutionInput = input.routing?.resolution;
@@ -980,6 +1105,10 @@ function resolveRouteSelectors(selectors, routes, policy) {
 }
 
 // src/fanout.ts
+function abortedError() {
+  return new AiConnectError("aborted", "Operation aborted.");
+}
+var MAX_DELAY_MS = 24 * 60 * 60 * 1e3;
 function createFanoutLimiter(policy, runtime) {
   const now = () => runtime.now?.() ?? Date.now();
   const { maxConcurrency, requestsPerSecond, maxCalls } = policy;
@@ -1043,10 +1172,10 @@ function createFanoutLimiter(policy, runtime) {
           if (index >= 0) {
             concurrencyQueue.splice(index, 1);
           }
-          rejectWaiter(waiter, new AiConnectError("aborted", "Operation aborted."));
+          rejectWaiter(waiter, abortedError());
         };
         if (signal.aborted) {
-          reject(new AiConnectError("aborted", "Operation aborted."));
+          reject(abortedError());
           return;
         }
         waiter.signal = signal;
@@ -1062,7 +1191,7 @@ function createFanoutLimiter(policy, runtime) {
     }
     while (true) {
       if (signal?.aborted) {
-        throw new AiConnectError("aborted", "Operation aborted.");
+        throw abortedError();
       }
       refill();
       if (tokens >= 1) {
@@ -1074,6 +1203,7 @@ function createFanoutLimiter(policy, runtime) {
     }
   }
   function delay(ms, signal) {
+    const safeMs = Number.isFinite(ms) && ms >= 0 ? Math.min(ms, MAX_DELAY_MS) : MAX_DELAY_MS;
     return new Promise((resolve, reject) => {
       let cancelTimer;
       const onAbort = () => {
@@ -1081,11 +1211,11 @@ function createFanoutLimiter(policy, runtime) {
         if (signal) {
           signal.removeEventListener("abort", onAbort);
         }
-        reject(new AiConnectError("aborted", "Operation aborted."));
+        reject(abortedError());
       };
       if (signal) {
         if (signal.aborted) {
-          reject(new AiConnectError("aborted", "Operation aborted."));
+          reject(abortedError());
           return;
         }
         signal.addEventListener("abort", onAbort, { once: true });
@@ -1097,9 +1227,9 @@ function createFanoutLimiter(policy, runtime) {
         resolve();
       };
       if (runtime.setTimer) {
-        cancelTimer = runtime.setTimer(ms, done);
+        cancelTimer = runtime.setTimer(safeMs, done);
       } else {
-        const handle = setTimeout(done, ms);
+        const handle = setTimeout(done, safeMs);
         cancelTimer = () => clearTimeout(handle);
       }
     });
@@ -1113,8 +1243,13 @@ function createFanoutLimiter(policy, runtime) {
         );
       }
       callsStarted += 1;
-      await awaitRateToken(signal);
-      await awaitConcurrencySlot(signal);
+      try {
+        await awaitRateToken(signal);
+        await awaitConcurrencySlot(signal);
+      } catch (error) {
+        callsStarted -= 1;
+        throw error;
+      }
       let released = false;
       return () => {
         if (released) {
@@ -1198,19 +1333,54 @@ function isRemoteUrl(value) {
     return false;
   }
 }
+function mimeTypeAndExtensionFromMediaType(mediaTypeAndParams, fallbackMimeType, fallbackExtension) {
+  const mimeType = mediaTypeAndParams.split(";")[0]?.trim() || fallbackMimeType;
+  const extension2 = mimeType.split("/")[1] ?? fallbackExtension;
+  return { mimeType, extension: extension2 };
+}
 function parseDataUrl(value) {
-  const match = /^data:([^,]*?);base64,(.*)$/i.exec(value);
-  if (!match) {
-    return null;
+  const base64Match = /^data:([^,]*?);base64,(.*)$/i.exec(value);
+  if (base64Match) {
+    const { mimeType, extension: extension2 } = mimeTypeAndExtensionFromMediaType(
+      base64Match[1] ?? "",
+      "application/octet-stream",
+      "bin"
+    );
+    return {
+      mimeType,
+      extension: extension2,
+      data: base64Match[2] ?? ""
+    };
   }
-  const mediaTypeAndParams = match[1] ?? "";
-  const mimeType = mediaTypeAndParams.split(";")[0]?.trim() || "application/octet-stream";
-  const extension2 = mimeType.split("/")[1] ?? "bin";
-  return {
-    mimeType,
-    extension: extension2,
-    data: match[2] ?? ""
-  };
+  const plainMatch = /^data:([^,]*?),(.*)$/i.exec(value);
+  if (plainMatch) {
+    const { mimeType, extension: extension2 } = mimeTypeAndExtensionFromMediaType(
+      plainMatch[1] ?? "",
+      "text/plain",
+      "txt"
+    );
+    let decoded;
+    try {
+      decoded = decodeURIComponent(plainMatch[2] ?? "");
+    } catch {
+      throw new AiConnectError(
+        "validation_error",
+        "unsupported data URL encoding"
+      );
+    }
+    return {
+      mimeType,
+      extension: extension2,
+      data: encodeBase64(new TextEncoder().encode(decoded))
+    };
+  }
+  if (/^data:/i.test(value)) {
+    throw new AiConnectError(
+      "validation_error",
+      "unsupported data URL encoding"
+    );
+  }
+  return null;
 }
 function mimeTypeFromName(name) {
   const ext = extension(name);
@@ -1424,9 +1594,61 @@ async function materializePortableFile(file) {
       payload.dataUrl = `data:${mimeType};base64,${base64}`;
     }
   }
+  if (category === "other") {
+    const base64 = await portableFileToBase64(file);
+    if (base64 !== void 0) {
+      payload.base64 = base64;
+      payload.dataUrl = `data:${mimeType};base64,${base64}`;
+    } else if (!uri && !providerFileId) {
+      const droppedReason = `Portable file "${file.name}" (category "other", kind "${file.kind}") has no decodable byte source and no remote uri/providerFileId; its content was dropped and this payload carries metadata only.`;
+      payload.droppedReason = droppedReason;
+      payload.warnings = [...payload.warnings ?? [], droppedReason];
+    }
+  }
   return payload;
 }
-function preparePortableFile(input) {
+function collapsePathSegments(value) {
+  const normalized = value.replaceAll("\\", "/");
+  const isAbsolute = normalized.startsWith("/");
+  const segments = normalized.split("/");
+  const resolved = [];
+  for (const segment of segments) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      if (resolved.length > 0 && resolved[resolved.length - 1] !== "..") {
+        resolved.pop();
+      } else if (!isAbsolute) {
+        resolved.push("..");
+      }
+      continue;
+    }
+    resolved.push(segment);
+  }
+  return (isAbsolute ? "/" : "") + resolved.join("/");
+}
+function applyPathGuard(rawPath, guard) {
+  if (!guard) {
+    return rawPath;
+  }
+  if (guard === "basename") {
+    return basename(rawPath);
+  }
+  const resolved = collapsePathSegments(rawPath);
+  const withinAllowedRoot = guard.allowedRoots.some((root) => {
+    const resolvedRoot = collapsePathSegments(root);
+    return resolved === resolvedRoot || resolved.startsWith(`${resolvedRoot}/`);
+  });
+  if (!withinAllowedRoot) {
+    throw new AiConnectError(
+      "validation_error",
+      `Path "${rawPath}" is outside the configured allowedRoots for portable file attachments.`
+    );
+  }
+  return rawPath;
+}
+function preparePortableFile(input, options) {
   if (isPortableFile(input)) {
     return input;
   }
@@ -1452,11 +1674,12 @@ function preparePortableFile(input) {
         }
       };
     }
+    const guardedPath = applyPathGuard(input, options?.pathGuard);
     return {
-      id: `path:${input}`,
+      id: `path:${guardedPath}`,
       kind: "path",
-      name: basename(input),
-      source: input
+      name: basename(guardedPath),
+      source: guardedPath
     };
   }
   if (isRemoteReference(input)) {
@@ -1497,17 +1720,76 @@ function preparePortableFile(input) {
 }
 
 // src/logging.ts
+var REDACT_KEYS = /* @__PURE__ */ new Set([
+  "apikey",
+  "authorization",
+  "password",
+  "token",
+  "x-api-key",
+  "x-goog-api-key"
+]);
+var REDACTED = "[REDACTED]";
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var SECRET_PREFIX_RE = /^(sk-|sk-ant-|xox[baprs]-|ghp_|gho_|AIza)/;
+function looksLikeSecretValue(value) {
+  if (UUID_RE.test(value)) {
+    return false;
+  }
+  if (/^Bearer\s+/i.test(value)) {
+    return true;
+  }
+  if (SECRET_PREFIX_RE.test(value)) {
+    return true;
+  }
+  return /^[A-Za-z0-9+/=_]{40,}$/.test(value);
+}
+function redactNode(node) {
+  if (node === null || node === void 0) {
+    return node;
+  }
+  if (typeof node === "string") {
+    return looksLikeSecretValue(node) ? REDACTED : node;
+  }
+  if (typeof node !== "object") {
+    return node;
+  }
+  if (Array.isArray(node)) {
+    return node.map((item) => redactNode(item));
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(node)) {
+    result[key] = REDACT_KEYS.has(key.toLowerCase()) ? REDACTED : redactNode(value);
+  }
+  return result;
+}
+function redactEvent(event) {
+  return redactNode(event);
+}
+function redactBaseUrl(url) {
+  try {
+    const parsed = new URL(url);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    const withoutHash = url.split("#")[0] ?? url;
+    return withoutHash.split("?")[0] ?? withoutHash;
+  }
+}
 function createConsoleWideEventLogger(options = {}) {
   const write = options.write ?? ((line) => {
     console.info(line);
   });
   return (event) => {
+    const redacted = redactEvent(event);
     write(
-      options.pretty ? JSON.stringify(event, null, 2) : JSON.stringify(event)
+      options.pretty ? JSON.stringify(redacted, null, 2) : JSON.stringify(redacted)
     );
   };
 }
-async function shouldEmitWideEvent(event, options = {}) {
+async function shouldEmitWideEvent(event, options = {}, random = Math.random) {
   const sampleRate = options.sampleRate ?? 1;
   if ((options.keepErrors ?? true) && event.outcome === "error") {
     return true;
@@ -1541,7 +1823,7 @@ async function shouldEmitWideEvent(event, options = {}) {
   if (sampleRate >= 1) {
     return true;
   }
-  return Math.random() < sampleRate;
+  return random() < sampleRate;
 }
 
 // src/router.ts
@@ -1606,6 +1888,19 @@ function buildWeightedOrder(routes) {
   }
   return expanded;
 }
+var ROUTING_STRATEGIES = {
+  priority: (ordered) => ordered,
+  failover: (ordered) => ordered,
+  "round-robin": (ordered, cursor, cursorKey) => {
+    const index = cursor(cursorKey, ordered.length);
+    return rotate(ordered, index);
+  },
+  "weighted-round-robin": (ordered, cursor, cursorKey) => {
+    const weighted = buildWeightedOrder(ordered);
+    const index = cursor(cursorKey, weighted.length);
+    return unique(rotate(weighted, index));
+  }
+};
 var RouteRegistry = class {
   config;
   runtime;
@@ -1676,14 +1971,21 @@ 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 available = 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)).filter((route) => {
-      const state = this.getHealth(route).state;
-      return state !== "cooling_down" && state !== "unavailable";
-    }).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(route, 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(
+      eligible.filter((route) => {
+        const state = this.getHealth(route).state;
+        return state !== "cooling_down" && state !== "unavailable";
+      }).map((route) => route.id)
+    );
     return this.#order(
-      request.routeHints?.strategy ?? operationRouting.strategy,
-      available,
-      request.routeHints?.preferredProviders
+      strategy,
+      eligible,
+      healthyIds,
+      request.routeHints?.preferredProviders,
+      cursorKey
     );
   }
   recordSuccess(route) {
@@ -1716,20 +2018,12 @@ var RouteRegistry = class {
       failureCount
     });
   }
-  #order(strategy, routes, preferredProviders) {
-    const sorted = baseSort(routes, preferredProviders);
-    const cursorKey = `${strategy}:${sorted.map((route) => route.id).join("|")}`;
-    const ordered = this.config.routing.shuffleOnInit ? this.#shuffle(cursorKey, sorted) : sorted;
-    if (strategy === "priority" || strategy === "failover") {
-      return ordered;
-    }
-    if (strategy === "round-robin") {
-      const index2 = this.#cursor(cursorKey, ordered.length);
-      return rotate(ordered, index2);
-    }
-    const weighted = buildWeightedOrder(ordered);
-    const index = this.#cursor(cursorKey, weighted.length);
-    return unique(rotate(weighted, index));
+  #order(strategy, eligible, healthyIds, preferredProviders, cursorKey) {
+    const sorted = baseSort(eligible, preferredProviders);
+    const orderedFull = 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);
   }
   #shuffle(key, routes) {
     const cached = this.#shuffles.get(key);
@@ -1833,8 +2127,22 @@ var MODEL_REFERENCE = {
   "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);
@@ -1842,6 +2150,7 @@ function normalizeModelKey(model) {
   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) {
@@ -1864,7 +2173,7 @@ function lookupModelRef(model) {
   }
   let substringWinner;
   for (const [key, entry] of Object.entries(MODEL_REFERENCE)) {
-    if (normalized.includes(key)) {
+    if (key.length >= MIN_SUBSTRING_MATCH_KEY_LENGTH && normalized.includes(key)) {
       if (!substringWinner || key.length > substringWinner.key.length) {
         substringWinner = entry;
       }
@@ -2096,6 +2405,14 @@ var DEFAULT_LOGGING_SERVICE = "ai-connect";
 function splitCredentialValues(value, delimiter) {
   return value.split(delimiter).map((item) => item.trim()).filter(Boolean);
 }
+var ClientToolExecutionError = class extends Error {
+  aiError;
+  constructor(aiError) {
+    super(aiError.message);
+    this.name = "ClientToolExecutionError";
+    this.aiError = aiError;
+  }
+};
 function materializeRuntimeConfig(config, runtime) {
   const routeExpansion = /* @__PURE__ */ new Map();
   const routes = [];
@@ -2110,13 +2427,14 @@ function materializeRuntimeConfig(config, runtime) {
       continue;
     }
     const expandedIds = [];
+    const expandedWeight = Math.max(1, Math.floor(route.weight / values.length));
     values.forEach((apiKey, index) => {
       const credentialId = `${route.credentialId}#${index + 1}`;
       const expandedRoute = {
         ...route,
         id: `${route.id}#${index + 1}`,
         credentialId,
-        weight: 1,
+        weight: expandedWeight,
         credential: {
           ...route.credential,
           id: credentialId,
@@ -2157,6 +2475,27 @@ async function sleep(delayMs) {
   }
   await new Promise((resolve) => setTimeout(resolve, delayMs));
 }
+async function runWithAbortRace(handlerPromise, abort) {
+  if (abort.signal.aborted) {
+    void Promise.resolve(handlerPromise).catch(() => {
+    });
+    throw mapAbortError(abort.reason);
+  }
+  let onAbort;
+  const abortPromise = new Promise((_, reject) => {
+    onAbort = () => reject(mapAbortError(abort.reason));
+    abort.signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([handlerPromise, abortPromise]);
+  } finally {
+    if (onAbort) {
+      abort.signal.removeEventListener("abort", onAbort);
+    }
+    void Promise.resolve(handlerPromise).catch(() => {
+    });
+  }
+}
 function normalizeWorkingDirectory(value) {
   if (value === void 0) {
     return void 0;
@@ -2198,6 +2537,12 @@ function normalizeClientToolRegistry(tools) {
   const registry = /* @__PURE__ */ new Map();
   for (const tool of tools ?? []) {
     const normalized = normalizeClientToolDefinition(tool);
+    if (registry.has(normalized.function.name)) {
+      throw new AiConnectError(
+        "validation_error",
+        `Duplicate client tool name "${normalized.function.name}" registered on this client.`
+      );
+    }
     registry.set(normalized.function.name, normalized);
   }
   return registry;
@@ -2223,10 +2568,22 @@ function resolveClientToolSelections(selections, registry) {
           `No client tool named "${name}" is registered on this client.`
         );
       }
+      if (resolved.has(name)) {
+        throw new AiConnectError(
+          "validation_error",
+          `Duplicate client tool "${name}" in the clientTools selection.`
+        );
+      }
       resolved.set(name, registered);
       continue;
     }
     const normalized = normalizeClientToolDefinition(selection);
+    if (resolved.has(normalized.function.name)) {
+      throw new AiConnectError(
+        "validation_error",
+        `Duplicate client tool "${normalized.function.name}" in the clientTools selection.`
+      );
+    }
     resolved.set(normalized.function.name, normalized);
   }
   return Array.from(resolved.values());
@@ -2265,6 +2622,73 @@ function normalizeToolResult(result) {
     ...result.isError !== void 0 ? { isError: result.isError } : {}
   };
 }
+var MAX_CLIENT_TOOL_LOOP_DEPTH = 8;
+async function* executeToolCallsRound(params) {
+  const { toolCalls, registry, route, request, runtime, messages, abort } = params;
+  const assistantMessage = {
+    role: "assistant",
+    content: params.assistantText,
+    toolCalls
+  };
+  const toolMessages = [];
+  for (const toolCall of toolCalls) {
+    const tool = registry.get(toolCall.name);
+    if (!tool) {
+      throw new ClientToolExecutionError(
+        new AiConnectError(
+          "validation_error",
+          `No client tool handler is registered for "${toolCall.name}".`
+        )
+      );
+    }
+    if (abort.signal.aborted) {
+      throw mapAbortError(abort.reason);
+    }
+    const startEvent = params.onToolStart?.(toolCall);
+    if (startEvent) {
+      yield startEvent;
+    }
+    let execution;
+    try {
+      execution = normalizeToolResult(
+        await tool.execute(toolCall.arguments, {
+          route,
+          request,
+          runtime,
+          toolCall,
+          messages,
+          ...request.workingDirectory ? { workingDirectory: request.workingDirectory } : {}
+        })
+      );
+    } catch (error) {
+      if (abort.signal.aborted) {
+        throw mapAbortError(abort.reason);
+      }
+      throw new ClientToolExecutionError(
+        new AiConnectError(
+          "validation_error",
+          `Client tool "${tool.function.name}" threw during execution: ${error instanceof Error ? error.message : String(error)}`,
+          { cause: error }
+        )
+      );
+    }
+    toolMessages.push({
+      role: "tool",
+      content: execution.content,
+      toolName: tool.function.name,
+      toolCallId: toolCall.id,
+      ...execution.data !== void 0 ? { data: execution.data } : {},
+      ...execution.isError !== void 0 ? { isError: execution.isError } : {}
+    });
+    const finishEvent = params.onToolFinish?.(toolCall, {
+      ...execution.isError !== void 0 ? { isError: execution.isError } : {}
+    });
+    if (finishEvent) {
+      yield finishEvent;
+    }
+  }
+  return { assistantMessage, toolMessages };
+}
 function sumOptionalNumbers(left, right) {
   if (left === void 0) {
     return right;
@@ -2339,6 +2763,34 @@ function requiresImageInput(request) {
 function requiresFileUpload(request) {
   return request.attachments.some((file) => isPortableDocumentFile(file));
 }
+function resolveRequiredCapabilities(request) {
+  const requiresSchema = requiresToolSchema(request);
+  const requiresClientTools = requiresClientToolExecution(request);
+  const requiresImage = requiresImageInput(request);
+  const requiresFile = requiresFileUpload(request);
+  const requiresAnyCapability = requiresSchema || requiresClientTools || requiresImage || requiresFile;
+  const projected = requiresAnyCapability ? {
+    ...request,
+    routeHints: {
+      ...request.routeHints ?? {},
+      requiredCapabilities: {
+        ...request.routeHints?.requiredCapabilities ?? {},
+        ...requiresSchema ? { supportsToolSchema: true } : {},
+        ...requiresClientTools ? { supportsClientToolExecution: true } : {},
+        ...requiresImage ? { supportsImageInput: true } : {},
+        ...requiresFile ? { supportsFileUpload: true } : {}
+      }
+    }
+  } : request;
+  return {
+    requiresSchema,
+    requiresClientTools,
+    requiresImage,
+    requiresFile,
+    requiresAnyCapability,
+    request: projected
+  };
+}
 function normalizeRequestBase(request) {
   if (request.messages.length === 0) {
     throw new AiConnectError("validation_error", "Unified generate/stream requests must include at least one message.");
@@ -2547,7 +2999,10 @@ function summarizeRoute(route) {
     model: route.model,
     handlerKey: route.handlerKey,
     profileId: route.profileId,
-    ...route.transport.baseUrl ? { baseUrl: route.transport.baseUrl } : {}
+    // SYS-3 / C1a: never emit a raw baseUrl into a wide event — a token embedded in
+    // userinfo (`https://user:secret@host`) or the query string would leak verbatim,
+    // unlike the secret-safe toPublicRoute projection. Strip credentials first.
+    ...route.transport.baseUrl ? { baseUrl: redactBaseUrl(route.transport.baseUrl) } : {}
   };
 }
 function summarizeFiles(files) {
@@ -2837,7 +3292,7 @@ function createClient(configOrInput, options = {}) {
     let output = initialOutput;
     let messages = [...request.messages];
     let transportSummary2;
-    for (let round = 0; round < 8; round += 1) {
+    for (let round = 0; ; round += 1) {
       const toolCalls = output.toolCalls ?? [];
       if (toolCalls.length === 0) {
         return {
@@ -2849,66 +3304,58 @@ function createClient(configOrInput, options = {}) {
           ...transportSummary2 ? { transportSummary: transportSummary2 } : {}
         };
       }
-      const assistantMessage = {
-        role: "assistant",
-        content: output.text ?? "",
-        toolCalls
-      };
-      const toolMessages = [];
-      for (const toolCall of toolCalls) {
-        const tool = registry.get(toolCall.name);
-        if (!tool) {
-          throw new AiConnectError(
-            "validation_error",
-            `No client tool handler is registered for "${toolCall.name}".`
-          );
-        }
-        const execution = normalizeToolResult(
-          await tool.execute(toolCall.arguments, {
-            route,
-            request,
-            runtime,
-            toolCall,
-            messages,
-            ...request.workingDirectory ? { workingDirectory: request.workingDirectory } : {}
-          })
-        );
-        toolMessages.push({
-          role: "tool",
-          content: execution.content,
-          toolName: tool.function.name,
-          toolCallId: toolCall.id,
-          ...execution.data !== void 0 ? { data: execution.data } : {},
-          ...execution.isError !== void 0 ? { isError: execution.isError } : {}
-        });
+      const roundIterator = executeToolCallsRound({
+        toolCalls,
+        assistantText: output.text ?? "",
+        registry,
+        route,
+        request,
+        runtime,
+        messages,
+        abort
+      });
+      let roundStep = await roundIterator.next();
+      while (!roundStep.done) {
+        roundStep = await roundIterator.next();
       }
-      messages = [...messages, assistantMessage, ...toolMessages];
+      messages = [
+        ...messages,
+        roundStep.value.assistantMessage,
+        ...roundStep.value.toolMessages
+      ];
       if (abort.signal.aborted) {
         throw mapAbortError(abort.reason);
       }
-      output = await handler({
-        route,
-        request: {
-          ...request,
-          messages,
-          attachments: []
-        },
-        runtime,
-        attempt: baseAttempt,
-        abort,
-        telemetry: {
-          captureTransport(summary) {
-            transportSummary2 = summary;
+      if (round + 1 >= MAX_CLIENT_TOOL_LOOP_DEPTH) {
+        throw new ClientToolExecutionError(
+          new AiConnectError(
+            "validation_error",
+            `clientTools exceeded the maximum tool-call loop depth of ${MAX_CLIENT_TOOL_LOOP_DEPTH}.`
+          )
+        );
+      }
+      output = await runWithAbortRace(
+        handler({
+          route,
+          request: {
+            ...request,
+            messages,
+            attachments: []
+          },
+          runtime,
+          attempt: baseAttempt,
+          abort,
+          telemetry: {
+            captureTransport(summary) {
+              transportSummary2 = summary;
+            }
           }
-        }
-      });
+        }),
+        abort
+      );
       warnings.push(...output.warnings ?? []);
       usage = mergeUsage(usage, output.usage);
     }
-    throw new AiConnectError(
-      "validation_error",
-      "clientTools exceeded the maximum tool-call loop depth of 8."
-    );
   }
   async function emitWideEvent(event) {
     if (!logging?.logger) {
@@ -2938,26 +3385,8 @@ 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 requiresSchema = requiresToolSchema(normalizedRequest);
-    const requiresClientTools = requiresClientToolExecution(normalizedRequest);
-    const requiresImage = requiresImageInput(normalizedRequest);
-    const requiresFile = requiresFileUpload(normalizedRequest);
-    const requiresAnyCapability = requiresSchema || requiresClientTools || requiresImage || requiresFile;
-    const resolvedCandidates = router.resolveCandidates(
-      requiresAnyCapability ? {
-        ...normalizedRequest,
-        routeHints: {
-          ...normalizedRequest.routeHints ?? {},
-          requiredCapabilities: {
-            ...normalizedRequest.routeHints?.requiredCapabilities ?? {},
-            ...requiresSchema ? { supportsToolSchema: true } : {},
-            ...requiresClientTools ? { supportsClientToolExecution: true } : {},
-            ...requiresImage ? { supportsImageInput: true } : {},
-            ...requiresFile ? { supportsFileUpload: true } : {}
-          }
-        }
-      } : normalizedRequest
-    );
+    const { requiresImage, requiresFile, 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) {
@@ -3045,18 +3474,21 @@ function createClient(configOrInput, options = {}) {
         const attemptStartedAt = nowMs(runtime);
         let transportSummary2;
         try {
-          let output = await handler.generate({
-            route,
-            request: routeRequest,
-            runtime,
-            attempt: attempts.length + 1,
-            abort,
-            telemetry: {
-              captureTransport(summary) {
-                transportSummary2 = summary;
+          let output = await runWithAbortRace(
+            handler.generate({
+              route,
+              request: routeRequest,
+              runtime,
+              attempt: attempts.length + 1,
+              abort,
+              telemetry: {
+                captureTransport(summary) {
+                  transportSummary2 = summary;
+                }
               }
-            }
-          });
+            }),
+            abort
+          );
           if (routeRequest.clientTools?.length && output.toolCalls?.length) {
             const loopResult = await executeClientToolLoop(
               route,
@@ -3071,6 +3503,9 @@ function createClient(configOrInput, options = {}) {
               transportSummary2 = loopResult.transportSummary;
             }
           }
+          if (abort.signal.aborted) {
+            throw mapAbortError(abort.reason);
+          }
           wideAttempts.push({
             index: wideAttempts.length + 1,
             route: routeSummary,
@@ -3141,6 +3576,49 @@ function createClient(configOrInput, options = {}) {
               routeId: route.id
             });
           }
+          if (error instanceof ClientToolExecutionError) {
+            const toolError = error.aiError;
+            attempts.push({
+              routeId: route.id,
+              handlerKey: route.handlerKey,
+              errorCode: toolError.code,
+              message: toolError.message
+            });
+            wideAttempts.push({
+              index: wideAttempts.length + 1,
+              route: routeSummary,
+              durationMs: nowMs(runtime) - attemptStartedAt,
+              outcome: "error",
+              retryCount,
+              errorCode: toolError.code,
+              message: toolError.message,
+              ...transportSummary2 ? { transport: transportSummary2 } : {}
+            });
+            await emitWideEvent({
+              timestamp: isoTimestamp(startedAt),
+              event: "ai_connect.operation",
+              requestId,
+              operationName,
+              operation: normalizedRequest.operation,
+              runtime: runtime.kind,
+              outcome: "error",
+              durationMs: nowMs(runtime) - startedAt,
+              candidates,
+              attempts: wideAttempts,
+              request: requestSummary,
+              error: {
+                code: toolError.code,
+                message: toolError.message,
+                routeId: route.id
+              },
+              ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+            });
+            throw new AiConnectError(toolError.code, toolError.message, {
+              ...toolError.details,
+              attempts,
+              routeId: route.id
+            });
+          }
           const normalizedError = toAiConnectError(error);
           const actions = config.routing.fallback.on[normalizedError.code] ?? [];
           attempts.push({
@@ -3385,30 +3863,16 @@ function createClient(configOrInput, options = {}) {
     return report;
   }
   async function runPingWithAbort(route, handler, abort) {
-    if (abort.signal.aborted) {
-      throw mapAbortError(abort.reason);
-    }
-    const handlerPromise = handler({
-      route,
-      request: buildPingRequest(),
-      runtime,
-      attempt: 1,
+    return runWithAbortRace(
+      handler({
+        route,
+        request: buildPingRequest(),
+        runtime,
+        attempt: 1,
+        abort
+      }),
       abort
-    });
-    let onAbort;
-    const abortPromise = new Promise((_, reject) => {
-      onAbort = () => reject(mapAbortError(abort.reason));
-      abort.signal.addEventListener("abort", onAbort, { once: true });
-    });
-    try {
-      return await Promise.race([handlerPromise, abortPromise]);
-    } finally {
-      if (onAbort) {
-        abort.signal.removeEventListener("abort", onAbort);
-      }
-      void Promise.resolve(handlerPromise).catch(() => {
-      });
-    }
+    );
   }
   async function checkEndpointReachable(route, handler, abort) {
     if (abort.signal.aborted) {
@@ -3951,12 +4415,6 @@ function createClient(configOrInput, options = {}) {
     },
     async *stream(request, opts) {
       const preparedRequest = prepareRequest(request);
-      if (preparedRequest.clientTools?.length) {
-        throw new AiConnectError(
-          "not_supported",
-          "clientTools are currently supported only by generate(), not stream()."
-        );
-      }
       const { abort, dispose: disposeAbort } = deriveAbort(
         opts,
         resolveOpTimeout(opts, "generateMs", options.timeouts),
@@ -3976,27 +4434,26 @@ function createClient(configOrInput, options = {}) {
         release = await limiter.acquire(abort.signal);
         const selectedModel = await resolveSelectedModel(preparedRequest);
         const normalizedRequest = withSelectedModel(preparedRequest, selectedModel);
-        const requiresSchema = requiresToolSchema(normalizedRequest);
-        const candidates = router.resolveCandidates(
-          requiresSchema ? {
-            ...normalizedRequest,
-            routeHints: {
-              ...normalizedRequest.routeHints ?? {},
-              requiredCapabilities: {
-                ...normalizedRequest.routeHints?.requiredCapabilities ?? {},
-                supportsToolSchema: true
-              }
-            }
-          } : normalizedRequest
-        );
+        const {
+          requiresImage,
+          requiresFile,
+          requiresClientTools,
+          request: capabilityScopedRequest
+        } = resolveRequiredCapabilities(normalizedRequest);
+        const candidates = router.resolveCandidates(capabilityScopedRequest);
         const startedAt = nowMs(runtime);
         const requestId = resolveEventRequestId(normalizedRequest.logContext);
         const candidateSummaries = candidates.map(summarizeRoute);
         const requestSummary = summarizeRequest(normalizedRequest, candidateSummaries);
         const attempts = [];
         const wideAttempts = [];
+        let hasYieldedOutward = false;
+        let sawStreamHandler = false;
         if (candidates.length === 0) {
-          const error = new AiConnectError("not_supported", `No eligible routes are available for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`);
+          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}".`
+          ) : new AiConnectError("not_supported", `No eligible routes are available for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`);
           await emitWideEvent({
             timestamp: isoTimestamp(startedAt),
             event: "ai_connect.operation",
@@ -4023,84 +4480,202 @@ function createClient(configOrInput, options = {}) {
             continue;
           }
           if (handler.stream) {
+            sawStreamHandler = true;
             const routeSummary = summarizeRoute(route);
             const attemptStartedAt = nowMs(runtime);
             let lastResult;
             let accumulatedText = "";
             const routeRequest = applyRouteDefaults(route, normalizedRequest);
-            const iterable = handler.stream({
-              route,
-              request: routeRequest,
-              runtime,
-              attempt: 1,
-              abort
-            });
-            const iterator = iterable[Symbol.asyncIterator]();
-            let iteratorReturned = false;
-            const returnIterator = async () => {
-              if (iteratorReturned) {
-                return;
-              }
-              iteratorReturned = true;
-              try {
-                await iterator.return?.();
-              } catch {
-              }
-            };
+            const roundTools = routeRequest.clientTools ?? [];
+            const registry = new Map(
+              roundTools.map((tool) => [tool.function.name, tool])
+            );
+            let loopMessages = routeRequest.messages;
+            let aggregatedUsage;
+            const aggregatedWarnings = [];
+            let toolRoundsExecuted = 0;
             try {
-              while (true) {
+              roundsLoop: for (let round = 0; ; round += 1) {
+                if (round >= MAX_CLIENT_TOOL_LOOP_DEPTH) {
+                  throw new ClientToolExecutionError(
+                    new AiConnectError(
+                      "validation_error",
+                      `clientTools exceeded the maximum tool-call loop depth of ${MAX_CLIENT_TOOL_LOOP_DEPTH}.`
+                    )
+                  );
+                }
                 if (abort.signal.aborted) {
-                  await returnIterator();
                   throw mapAbortError(abort.reason);
                 }
-                if (pauseSignal?.aborted) {
+                const roundRequest = round === 0 ? routeRequest : { ...routeRequest, messages: loopMessages, attachments: [] };
+                const iterable = handler.stream({
+                  route,
+                  request: roundRequest,
+                  runtime,
+                  attempt: 1,
+                  abort
+                });
+                const iterator = iterable[Symbol.asyncIterator]();
+                let iteratorReturned = false;
+                const returnIterator = async () => {
+                  if (iteratorReturned) {
+                    return;
+                  }
+                  iteratorReturned = true;
+                  try {
+                    await iterator.return?.();
+                  } catch {
+                  }
+                };
+                let roundResult;
+                try {
+                  while (true) {
+                    if (abort.signal.aborted) {
+                      await returnIterator();
+                      throw mapAbortError(abort.reason);
+                    }
+                    if (pauseSignal?.aborted) {
+                      await returnIterator();
+                      const pausedResult = lastResult ?? {
+                        route,
+                        text: accumulatedText,
+                        attachments: [],
+                        warnings: [],
+                        attempts
+                      };
+                      wideAttempts.push({
+                        index: wideAttempts.length + 1,
+                        route: routeSummary,
+                        durationMs: nowMs(runtime) - attemptStartedAt,
+                        outcome: "success",
+                        retryCount: 0
+                      });
+                      await emitWideEvent({
+                        timestamp: isoTimestamp(startedAt),
+                        event: "ai_connect.operation",
+                        requestId,
+                        operationName: "stream",
+                        operation: normalizedRequest.operation,
+                        runtime: runtime.kind,
+                        outcome: "success",
+                        durationMs: nowMs(runtime) - startedAt,
+                        candidates: candidateSummaries,
+                        attempts: wideAttempts,
+                        selectedRoute: routeSummary,
+                        request: requestSummary,
+                        result: summarizeResult(pausedResult),
+                        ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+                      });
+                      yield { type: "paused", result: pausedResult };
+                      return;
+                    }
+                    const next = await iterator.next();
+                    if (next.done) {
+                      break;
+                    }
+                    const event = next.value;
+                    if (event.type === "delta") {
+                      accumulatedText += event.text;
+                      hasYieldedOutward = true;
+                      yield event;
+                      continue;
+                    }
+                    if (event.type === "paused") {
+                      lastResult = event.result;
+                      wideAttempts.push({
+                        index: wideAttempts.length + 1,
+                        route: routeSummary,
+                        durationMs: nowMs(runtime) - attemptStartedAt,
+                        outcome: "success",
+                        retryCount: 0
+                      });
+                      router.recordSuccess(route);
+                      await emitWideEvent({
+                        timestamp: isoTimestamp(startedAt),
+                        event: "ai_connect.operation",
+                        requestId,
+                        operationName: "stream",
+                        operation: normalizedRequest.operation,
+                        runtime: runtime.kind,
+                        outcome: "success",
+                        durationMs: nowMs(runtime) - startedAt,
+                        candidates: candidateSummaries,
+                        attempts: wideAttempts,
+                        selectedRoute: routeSummary,
+                        request: requestSummary,
+                        result: summarizeResult(event.result),
+                        ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+                      });
+                      yield event;
+                      return;
+                    }
+                    if (event.type === "result") {
+                      roundResult = event.result;
+                      break;
+                    }
+                  }
+                } finally {
                   await returnIterator();
-                  const pausedResult = lastResult ?? {
-                    route,
-                    text: accumulatedText,
-                    attachments: [],
-                    warnings: [],
-                    attempts
-                  };
-                  wideAttempts.push({
-                    index: wideAttempts.length + 1,
-                    route: routeSummary,
-                    durationMs: nowMs(runtime) - attemptStartedAt,
-                    outcome: "success",
-                    retryCount: 0
-                  });
-                  await emitWideEvent({
-                    timestamp: isoTimestamp(startedAt),
-                    event: "ai_connect.operation",
-                    requestId,
-                    operationName: "stream",
-                    operation: normalizedRequest.operation,
-                    runtime: runtime.kind,
-                    outcome: "success",
-                    durationMs: nowMs(runtime) - startedAt,
-                    candidates: candidateSummaries,
-                    attempts: wideAttempts,
-                    selectedRoute: routeSummary,
-                    request: requestSummary,
-                    result: summarizeResult(pausedResult),
-                    ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
-                  });
-                  yield { type: "paused", result: pausedResult };
-                  return;
                 }
-                const next = await iterator.next();
-                if (next.done) {
-                  break;
+                if (!roundResult) {
+                  break roundsLoop;
+                }
+                if (registry.size === 0 || !roundResult.toolCalls?.length) {
+                  if (toolRoundsExecuted === 0) {
+                    lastResult = roundResult;
+                  } else {
+                    const mergedUsage = mergeUsage(aggregatedUsage, roundResult.usage);
+                    lastResult = {
+                      ...roundResult,
+                      warnings: [
+                        ...aggregatedWarnings,
+                        ...roundResult.warnings ?? []
+                      ],
+                      ...mergedUsage ? { usage: mergedUsage } : {}
+                    };
+                  }
+                  yield { type: "result", result: lastResult };
+                  break roundsLoop;
                 }
-                const event = next.value;
-                if (event.type === "delta") {
-                  accumulatedText += event.text;
-                  yield event;
-                  continue;
+                aggregatedUsage = mergeUsage(aggregatedUsage, roundResult.usage);
+                aggregatedWarnings.push(...roundResult.warnings ?? []);
+                const roundGen = executeToolCallsRound({
+                  toolCalls: roundResult.toolCalls,
+                  assistantText: roundResult.text ?? "",
+                  registry,
+                  route,
+                  request: routeRequest,
+                  runtime,
+                  messages: loopMessages,
+                  abort,
+                  // D3/UR-007: emit a `tool-call` BEFORE execute, `tool-result` AFTER.
+                  onToolStart: (toolCall) => ({
+                    type: "tool-call",
+                    toolCall: {
+                      id: toolCall.id,
+                      name: toolCall.name,
+                      arguments: toolCall.arguments
+                    }
+                  }),
+                  onToolFinish: (toolCall, execution) => ({
+                    type: "tool-result",
+                    toolCallId: toolCall.id,
+                    name: toolCall.name,
+                    ...execution.isError !== void 0 ? { isError: execution.isError } : {}
+                  })
+                });
+                let toolStep = await roundGen.next();
+                while (!toolStep.done) {
+                  hasYieldedOutward = true;
+                  yield toolStep.value;
+                  toolStep = await roundGen.next();
                 }
-                lastResult = event.result;
-                yield event;
-                break;
+                loopMessages = [
+                  ...loopMessages,
+                  toolStep.value.assistantMessage,
+                  ...toolStep.value.toolMessages
+                ];
+                toolRoundsExecuted += 1;
               }
               wideAttempts.push({
                 index: wideAttempts.length + 1,
@@ -4128,7 +4703,44 @@ function createClient(configOrInput, options = {}) {
               });
               return;
             } catch (error) {
-              await returnIterator();
+              if (error instanceof ClientToolExecutionError && !abort.signal.aborted) {
+                const toolError = error.aiError;
+                attempts.push({
+                  routeId: route.id,
+                  handlerKey: route.handlerKey,
+                  errorCode: toolError.code,
+                  message: toolError.message
+                });
+                wideAttempts.push({
+                  index: wideAttempts.length + 1,
+                  route: routeSummary,
+                  durationMs: nowMs(runtime) - attemptStartedAt,
+                  outcome: "error",
+                  retryCount: 0,
+                  errorCode: toolError.code,
+                  message: toolError.message
+                });
+                await emitWideEvent({
+                  timestamp: isoTimestamp(startedAt),
+                  event: "ai_connect.operation",
+                  requestId,
+                  operationName: "stream",
+                  operation: normalizedRequest.operation,
+                  runtime: runtime.kind,
+                  outcome: "error",
+                  durationMs: nowMs(runtime) - startedAt,
+                  candidates: candidateSummaries,
+                  attempts: wideAttempts,
+                  request: requestSummary,
+                  error: {
+                    code: toolError.code,
+                    message: toolError.message,
+                    routeId: route.id
+                  },
+                  ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+                });
+                throw toolError;
+              }
               const normalizedError = abort.signal.aborted ? mapAbortError(abort.reason) : toAiConnectError(error);
               attempts.push({
                 routeId: route.id,
@@ -4167,6 +4779,28 @@ function createClient(configOrInput, options = {}) {
                 });
                 throw normalizedError;
               }
+              if (hasYieldedOutward) {
+                await emitWideEvent({
+                  timestamp: isoTimestamp(startedAt),
+                  event: "ai_connect.operation",
+                  requestId,
+                  operationName: "stream",
+                  operation: normalizedRequest.operation,
+                  runtime: runtime.kind,
+                  outcome: "error",
+                  durationMs: nowMs(runtime) - startedAt,
+                  candidates: candidateSummaries,
+                  attempts: wideAttempts,
+                  request: requestSummary,
+                  error: {
+                    code: normalizedError.code,
+                    message: normalizedError.message,
+                    routeId: route.id
+                  },
+                  ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+                });
+                throw normalizedError;
+              }
               router.recordFailure(route, normalizedError.code);
               continue;
             }
@@ -4182,6 +4816,12 @@ function createClient(configOrInput, options = {}) {
           attempts,
           wideAttempts
         });
+        if (requiresClientTools && !sawStreamHandler) {
+          result.warnings = [
+            ...result.warnings,
+            "Streaming tool-loop is not supported by the available route(s); returned a non-streamed result via the generate tool-loop."
+          ];
+        }
         yield {
           type: "result",
           result
@@ -4472,12 +5112,32 @@ function trimTrailingSlash(value) {
 function appendPath(baseUrl, suffix) {
   return `${trimTrailingSlash(baseUrl)}/${suffix.replace(/^\/+/, "")}`;
 }
+function isAbortError(error) {
+  if (error instanceof AiConnectError) {
+    return error.code === "aborted";
+  }
+  return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+function attachPartsToLastUserTurn(conversation, createEmptyUserTurn) {
+  let targetIndex = -1;
+  for (let index = conversation.length - 1; index >= 0; index -= 1) {
+    if (conversation[index]?.role === "user") {
+      targetIndex = index;
+      break;
+    }
+  }
+  if (targetIndex === -1) {
+    conversation.push(createEmptyUserTurn());
+    targetIndex = conversation.length - 1;
+  }
+  return conversation[targetIndex];
+}
 function resolveOpenAiEndpoint(route, operation) {
   const configured = route.transport.baseUrl?.trim();
   if (!configured) {
     return operation === "image" ? "https://api.openai.com/v1/images/generations" : "https://api.openai.com/v1/chat/completions";
   }
-  if (configured.endsWith("/chat/completions") || configured.endsWith("/images/generations")) {
+  if (operation === "text" && configured.endsWith("/chat/completions") || operation === "image" && configured.endsWith("/images/generations")) {
     return configured;
   }
   return appendPath(
@@ -5308,7 +5968,7 @@ async function uploadAnthropicFile(payload, uploader) {
   }
   try {
     const base = uploader.context.route.transport.baseUrl?.trim();
-    const root = base ? base.replace(/\/(messages|models)$/, "") : "https://api.anthropic.com/v1";
+    const root = base ? trimTrailingSlash(base).replace(/\/(messages|models)$/, "") : "https://api.anthropic.com/v1";
     const endpoint = appendPath(root, "/files");
     const form = new FormData();
     form.append(
@@ -5332,7 +5992,10 @@ async function uploadAnthropicFile(payload, uploader) {
     }
     const id = recordOf(data).id;
     return typeof id === "string" ? id : void 0;
-  } catch {
+  } catch (error) {
+    if (uploader.context.abort.signal.aborted || isAbortError(error)) {
+      throw error;
+    }
     return void 0;
   }
 }
@@ -5365,7 +6028,10 @@ async function uploadOpenAiFile(payload, uploader) {
     }
     const id = recordOf(data).id;
     return typeof id === "string" ? id : void 0;
-  } catch {
+  } catch (error) {
+    if (uploader.context.abort.signal.aborted || isAbortError(error)) {
+      throw error;
+    }
     return void 0;
   }
 }
@@ -5375,10 +6041,11 @@ async function uploadGeminiFile(payload, uploader) {
   }
   try {
     const base = uploader.context.route.transport.baseUrl?.trim();
-    const endpoint = base ? appendPath(
-      base.replace(/\/v1beta\/models.*$/, "/v1beta").replace(/\/+$/, ""),
+    const root = base ? trimTrailingSlash(base.replace(/\/v1beta\/models.*$/, "/v1beta")) : void 0;
+    const endpoint = root ? appendPath(
+      root.endsWith("/v1beta") ? `${root.slice(0, -"/v1beta".length)}/upload/v1beta` : `${root}/upload`,
       "/files"
-    ).replace("/v1beta/files", "/upload/v1beta/files") : "https://generativelanguage.googleapis.com/upload/v1beta/files";
+    ) : "https://generativelanguage.googleapis.com/upload/v1beta/files";
     const response = await uploader.fetchImpl(endpoint, {
       method: "POST",
       headers: {
@@ -5397,7 +6064,10 @@ async function uploadGeminiFile(payload, uploader) {
     const file = recordOf(recordOf(data).file);
     const uri = file.uri ?? recordOf(data).uri;
     return typeof uri === "string" ? uri : void 0;
-  } catch {
+  } catch (error) {
+    if (uploader.context.abort.signal.aborted || isAbortError(error)) {
+      throw error;
+    }
     return void 0;
   }
 }
@@ -5595,21 +6265,10 @@ function attachOpenAiParts(conversation, parts) {
   if (parts.length === 0) {
     return conversation;
   }
-  let targetIndex = -1;
-  for (let index = conversation.length - 1; index >= 0; index -= 1) {
-    if (conversation[index]?.role === "user") {
-      targetIndex = index;
-      break;
-    }
-  }
-  if (targetIndex === -1) {
-    conversation.push({
-      role: "user",
-      content: ""
-    });
-    targetIndex = conversation.length - 1;
-  }
-  const target = conversation[targetIndex];
+  const target = attachPartsToLastUserTurn(conversation, () => ({
+    role: "user",
+    content: ""
+  }));
   const baseParts = typeof target.content === "string" && target.content.trim().length > 0 ? [{ type: "text", text: target.content }] : Array.isArray(target.content) ? target.content : [];
   target.content = [...baseParts, ...parts];
   return conversation;
@@ -5695,21 +6354,10 @@ async function anthropicRequest(messages, attachments, uploader) {
   }
   const attachmentParts = await anthropicAttachmentParts(attachments, uploader);
   if (attachmentParts.length > 0) {
-    let targetIndex = -1;
-    for (let index = conversation.length - 1; index >= 0; index -= 1) {
-      if (conversation[index]?.role === "user") {
-        targetIndex = index;
-        break;
-      }
-    }
-    if (targetIndex === -1) {
-      conversation.push({
-        role: "user",
-        content: ""
-      });
-      targetIndex = conversation.length - 1;
-    }
-    const target = conversation[targetIndex];
+    const target = attachPartsToLastUserTurn(conversation, () => ({
+      role: "user",
+      content: ""
+    }));
     const baseParts = typeof target.content === "string" && target.content.trim().length > 0 ? [{ type: "text", text: target.content }] : Array.isArray(target.content) ? target.content : [];
     target.content = [...baseParts, ...attachmentParts];
   }
@@ -5720,12 +6368,27 @@ async function anthropicRequest(messages, attachments, uploader) {
 }
 async function geminiRequest(messages, attachments, uploader) {
   const system = messages.filter((message) => message.role === "system").map((message) => message.content).join("\n\n");
+  const toolNameByCallId = /* @__PURE__ */ new Map();
+  for (const message of messages) {
+    if (hasAssistantToolCalls(message)) {
+      for (const call of message.toolCalls) {
+        toolNameByCallId.set(call.id, call.name);
+      }
+    }
+  }
   const contents = messages.filter((message) => message.role !== "system").reduce(
     (conversation, message) => {
       if (isToolMessage(message)) {
+        const resolvedName = message.toolName ?? toolNameByCallId.get(message.toolCallId);
+        if (!resolvedName) {
+          throw new AiConnectError(
+            "validation_error",
+            `Gemini functionResponse requires a tool name: the tool message for toolCallId "${message.toolCallId}" has no toolName and no matching assistant toolCall was found.`
+          );
+        }
         const response = {
           functionResponse: {
-            name: message.toolName ?? "tool",
+            name: resolvedName,
             response: isRecord(message.data) ? message.data : {
               content: message.content,
               ...message.isError !== void 0 ? { isError: message.isError } : {}
@@ -5772,21 +6435,11 @@ async function geminiRequest(messages, attachments, uploader) {
   );
   const attachmentParts = await geminiAttachmentParts(attachments, uploader);
   if (attachmentParts.length > 0) {
-    let targetIndex = -1;
-    for (let index = contents.length - 1; index >= 0; index -= 1) {
-      if (contents[index]?.role === "user") {
-        targetIndex = index;
-        break;
-      }
-    }
-    if (targetIndex === -1) {
-      contents.push({
-        role: "user",
-        parts: []
-      });
-      targetIndex = contents.length - 1;
-    }
-    contents[targetIndex].parts.push(...attachmentParts);
+    const target = attachPartsToLastUserTurn(contents, () => ({
+      role: "user",
+      parts: []
+    }));
+    target.parts.push(...attachmentParts);
   }
   return {
     ...system ? {
@@ -5836,6 +6489,22 @@ function extractThoughts(value) {
   const joined = thoughts.join("\n").trim();
   return joined.length > 0 ? joined : void 0;
 }
+function extractThinking(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const thinking = value.flatMap((part) => {
+    if (part && typeof part === "object" && part.type === "thinking") {
+      const candidate = part.thinking;
+      if (typeof candidate === "string") {
+        return [candidate];
+      }
+    }
+    return [];
+  });
+  const joined = thinking.join("\n").trim();
+  return joined.length > 0 ? joined : void 0;
+}
 function imageAttachmentsFromPayload(payload, ...sources) {
   return extractImagePayloads(payload, ...sources).map(
     (item) => preparePortableFile(item)
@@ -5923,6 +6592,10 @@ function buildOpenAiChatBody(context, messages, parameters, responseFormat, opts
     model: context.route.model,
     messages,
     stream: opts.stream,
+    // Ask OpenAI-compatible streaming routes for the trailing usage chunk; without
+    // `stream_options.include_usage` the SSE stream carries no `usage` block and
+    // `runOpenAiStream` would always report `usage: undefined` (H5).
+    ...opts.stream ? { stream_options: { include_usage: true } } : {},
     ...parameters?.maxTokens !== void 0 ? { max_tokens: parameters.maxTokens } : {},
     ...parameters?.temperature !== void 0 ? { temperature: parameters.temperature } : {},
     ...parameters?.topP !== void 0 ? { top_p: parameters.topP } : {},
@@ -6077,6 +6750,11 @@ async function* runOpenAiStream(fetchImpl, context) {
   }
   const response = outcome.response;
   const streamWarnings = [...uploaderWarnings];
+  if (parameters?.candidateCount && parameters.candidateCount > 1) {
+    streamWarnings.push(
+      "candidateCount > 1 is forwarded to OpenAI-compatible text routes, but the normalized result returns only the first choice."
+    );
+  }
   if (droppedResponseFormat) {
     streamWarnings.push(
       "response_format was rejected by the OpenAI-compatible route (HTTP 400); the request was retried once without response_format and structured-output formatting was NOT enforced."
@@ -6222,8 +6900,7 @@ function buildOpenAiStreamResult(context, text, toolCalls, usage, warnings) {
     } : {}
   };
 }
-async function runOpenAiImage(fetchImpl, context) {
-  const apiKey = resolveApiKey(context.route, context.runtime);
+async function runProviderImage(fetchImpl, context, opts) {
   const referenceImages = imageReferenceFiles(context);
   const bundle = buildImagePromptBundle({
     request: context.request,
@@ -6232,10 +6909,10 @@ async function runOpenAiImage(fetchImpl, context) {
   });
   const baseFields = buildImageRequestFields(context, bundle);
   const useEditEndpoint = shouldUseImageEditEndpoint(context);
-  const endpoint = useEditEndpoint ? resolveOpenAiImageEditEndpoint(context.route) : resolveOpenAiEndpoint(context.route, "image");
+  const endpoint = useEditEndpoint ? opts.resolveEditEndpoint(context.route) : opts.resolveEndpoint(context.route);
   transportSummary(
     context,
-    useEditEndpoint ? "openai-image-edit" : "openai-image",
+    useEditEndpoint ? `${opts.providerLabel}-image-edit` : `${opts.providerLabel}-image`,
     endpoint,
     "POST",
     false,
@@ -6248,23 +6925,21 @@ async function runOpenAiImage(fetchImpl, context) {
   );
   const response = await fetchImpl(endpoint, useEditEndpoint ? {
     method: "POST",
-    headers: {
-      authorization: `Bearer ${apiKey}`
-    },
+    headers: { ...opts.authHeaders },
     body: await buildImageEditFormData(context, baseFields),
     signal: context.abort.signal
   } : {
     method: "POST",
     headers: {
       "content-type": "application/json",
-      authorization: `Bearer ${apiKey}`
+      ...opts.authHeaders
     },
     body: JSON.stringify(baseFields),
     signal: context.abort.signal
   });
   const payload = await readPayload(response);
   if (!response.ok) {
-    throw classifyApiError("openai", response, payload);
+    throw classifyApiError(opts.classifyProvider, response, payload);
   }
   return {
     data: {
@@ -6274,6 +6949,16 @@ async function runOpenAiImage(fetchImpl, context) {
     attachments: imageAttachmentsFromPayload(payload)
   };
 }
+async function runOpenAiImage(fetchImpl, context) {
+  const apiKey = resolveApiKey(context.route, context.runtime);
+  return runProviderImage(fetchImpl, context, {
+    resolveEndpoint: (route) => resolveOpenAiEndpoint(route, "image"),
+    resolveEditEndpoint: (route) => resolveOpenAiImageEditEndpoint(route),
+    authHeaders: { authorization: `Bearer ${apiKey}` },
+    providerLabel: "openai",
+    classifyProvider: "openai"
+  });
+}
 async function runAnthropic(fetchImpl, context) {
   const apiKey = resolveApiKey(context.route, context.runtime);
   const uploaderWarnings = [];
@@ -6285,6 +6970,8 @@ async function runAnthropic(fetchImpl, context) {
   const parameters = context.request.parameters;
   const requestBody = {
     model: context.route.model,
+    // Anthropic REQUIRES `max_tokens` (unlike OpenAI/Gemini, where it is optional), so a
+    // provider-specific default of 4096 is applied when the caller omits `maxTokens`.
     max_tokens: parameters?.maxTokens ?? 4096,
     ...parameters?.temperature !== void 0 ? { temperature: parameters.temperature } : {},
     ...parameters?.topP !== void 0 ? { top_p: parameters.topP } : {},
@@ -6314,8 +7001,12 @@ async function runAnthropic(fetchImpl, context) {
     throw classifyApiError("anthropic", response, payload);
   }
   const data = payload;
+  const anthropicReasoning = extractThinking(data.content);
   return {
     text: extractText(data.content),
+    // Anthropic extended-thinking blocks, separated from the answer (consumers route this
+    // to a thinking UI), mirroring the Gemini `reasoning` path.
+    ...anthropicReasoning ? { reasoning: anthropicReasoning } : {},
     data,
     ...anthropicToolCallsFromPayload(data).length > 0 ? { toolCalls: anthropicToolCallsFromPayload(data) } : {},
     ...uploaderWarnings.length > 0 ? { warnings: uploaderWarnings } : {},
@@ -6410,55 +7101,13 @@ async function runGemini(fetchImpl, context) {
 }
 async function runGeminiImage(fetchImpl, context) {
   const apiKey = resolveApiKey(context.route, context.runtime);
-  const referenceImages = imageReferenceFiles(context);
-  const bundle = buildImagePromptBundle({
-    request: context.request,
-    model: context.route.model,
-    referenceImages
+  return runProviderImage(fetchImpl, context, {
+    resolveEndpoint: (route) => resolveGeminiImageEndpoint(route),
+    resolveEditEndpoint: (route) => resolveGeminiImageEditEndpoint(route),
+    authHeaders: { authorization: `Bearer ${apiKey}` },
+    providerLabel: "gemini",
+    classifyProvider: context.route.provider
   });
-  const baseFields = buildImageRequestFields(context, bundle);
-  const useEditEndpoint = shouldUseImageEditEndpoint(context);
-  const endpoint = useEditEndpoint ? resolveGeminiImageEditEndpoint(context.route) : resolveGeminiImageEndpoint(context.route);
-  transportSummary(
-    context,
-    useEditEndpoint ? "gemini-image-edit" : "gemini-image",
-    endpoint,
-    "POST",
-    false,
-    {
-      ...baseFields,
-      source_image: Boolean(context.request.image?.sourceImage),
-      mask: Boolean(context.request.image?.mask),
-      reference_image_count: referenceImages.length
-    }
-  );
-  const response = await fetchImpl(endpoint, useEditEndpoint ? {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${apiKey}`
-    },
-    body: await buildImageEditFormData(context, baseFields),
-    signal: context.abort.signal
-  } : {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${apiKey}`
-    },
-    body: JSON.stringify(baseFields),
-    signal: context.abort.signal
-  });
-  const payload = await readPayload(response);
-  if (!response.ok) {
-    throw classifyApiError(context.route.provider, response, payload);
-  }
-  return {
-    data: {
-      request: bundle,
-      response: payload
-    },
-    attachments: imageAttachmentsFromPayload(payload)
-  };
 }
 function verifyApiRoute(route, runtime) {
   resolveApiKey(route, runtime);
@@ -6537,9 +7186,12 @@ var AI_CONNECT_DEFAULT_SERVER_PRESETS = {
     transportId: "opencode-server"
   }
 };
-var AI_CONNECT_DEFAULT_SERVER_COMMANDS = {
-  "opencode:opencode-server": AI_CONNECT_DEFAULT_SERVER_PRESETS.opencode.command
-};
+var AI_CONNECT_DEFAULT_SERVER_COMMANDS = Object.fromEntries(
+  Object.values(AI_CONNECT_DEFAULT_SERVER_PRESETS).map((preset) => [
+    `${preset.id}:${preset.transportId}`,
+    preset.command
+  ])
+);
 
 // src/catalog.ts
 var TEXT_PROVIDER_CATALOG = [