@nemesis-oss/ollama-sdk 1.10.0 → 1.11.0

package/dist/index.js

@@ -339,6 +339,23 @@ var OllamaAgentMaxIterationsError = class extends OllamaClientError {
     this.maxIterations = options.maxIterations;
   }
 };
+var OllamaAgentToolLoopError = class extends OllamaClientError {
+  /** Name of the tool whose identical call would exceed the repeat budget. */
+  toolName;
+  /** How many times this exact call would have executed including the rejected one. */
+  repeatedExecutions;
+  /** The configured per-signature execution budget. */
+  maxRepeatedToolCalls;
+  /** Canonical `name(args)` signature of the repeated call (very large payloads truncated). */
+  signature;
+  constructor(message, options) {
+    super(message, { ...options, code: "agent_tool_loop_detected", retryable: false });
+    this.toolName = options.toolName;
+    this.repeatedExecutions = options.repeatedExecutions;
+    this.maxRepeatedToolCalls = options.maxRepeatedToolCalls;
+    this.signature = options.signature;
+  }
+};
 var OllamaMcpError = class extends OllamaClientError {
   mcpMethod;
   toolName;
@@ -638,6 +655,15 @@ var EndpointRegistry = class {
   }
 };
 
+// src/transport/url.ts
+function joinUrlPath(baseUrl, path) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const tail = path.replace(/^\/+/, "");
+  if (tail === "") return base;
+  if (base === "") return `/${tail}`;
+  return `${base}/${tail}`;
+}
+
 // src/middleware.ts
 function composeMiddleware(middlewares, finalHandler) {
   return function runPipeline(initialRequest) {
@@ -1190,7 +1216,7 @@ var HttpClient = class {
     }
   }
   async request(options) {
-    const url = `${this.baseUrl}${options.path}`;
+    const url = joinUrlPath(this.baseUrl, options.path);
     const method = options.method ?? (options.body !== void 0 || options.rawBody !== void 0 ? "POST" : "GET");
     const headers = this.buildHeaders(options.headers);
     if (options.rawBody !== void 0 && !options.headers?.["Content-Type"]) {
@@ -1250,7 +1276,7 @@ var HttpClient = class {
    * can decode their provider-specific event payloads without duplicating transport logic.
    */
   async requestSseStream(options) {
-    const url = `${this.baseUrl}${options.path}`;
+    const url = joinUrlPath(this.baseUrl, options.path);
     const method = options.method ?? "POST";
     const headers = {
       ...this.buildHeaders(options.headers),
@@ -1317,7 +1343,7 @@ var HttpClient = class {
     );
   }
   async requestStream(options) {
-    const url = `${this.baseUrl}${options.path}`;
+    const url = joinUrlPath(this.baseUrl, options.path);
     const method = options.method ?? "POST";
     const headers = this.buildHeaders(options.headers);
     return withSpan(
@@ -2158,6 +2184,151 @@ function createTimeoutSignal(timeoutMs, userSignal) {
   return { signal: controller.signal, cancel };
 }
 
+// src/context-safety.ts
+var DEFAULT_CONTEXT_WARNING_THRESHOLD = 0.9;
+var IMAGE_TOKEN_ESTIMATE = 300;
+var CHARS_PER_TOKEN = 4;
+function isCjkCodePoint(code) {
+  return code >= 19968 && code <= 40959 || // CJK Unified Ideographs
+  code >= 13312 && code <= 19903 || // CJK Extension A
+  code >= 12352 && code <= 12543 || // Hiragana + Katakana
+  code >= 44032 && code <= 55215 || // Hangul syllables
+  code >= 63744 && code <= 64255 || // CJK Compatibility Ideographs
+  code >= 65280 && code <= 65519;
+}
+function estimateTokens(text) {
+  if (text.length === 0) return 0;
+  let cjk = 0;
+  let other = 0;
+  for (const char of text) {
+    if (isCjkCodePoint(char.codePointAt(0) ?? 0)) cjk += 1;
+    else other += 1;
+  }
+  return Math.ceil(cjk + other / CHARS_PER_TOKEN);
+}
+var MESSAGE_OVERHEAD_TOKENS = 4;
+function estimateMessageTokens(message) {
+  let total = MESSAGE_OVERHEAD_TOKENS + estimateTokens(message.content ?? "");
+  if (message.thinking !== void 0) total += estimateTokens(message.thinking);
+  if (message.tool_calls !== void 0) {
+    for (const call of message.tool_calls) {
+      total += estimateTokens(call.function.name);
+      total += estimateTokens(JSON.stringify(call.function.arguments ?? {}));
+    }
+  }
+  if (message.images !== void 0) total += message.images.length * IMAGE_TOKEN_ESTIMATE;
+  return total;
+}
+function estimateChatRequestTokens(req) {
+  let total = 0;
+  for (const message of req.messages) total += estimateMessageTokens(message);
+  if (req.tools !== void 0) {
+    for (const tool of req.tools) {
+      total += estimateTokens(tool.function.description ?? "");
+      total += estimateTokens(JSON.stringify(tool.function.parameters ?? {}));
+    }
+  }
+  return total;
+}
+function estimateGenerateRequestTokens(req) {
+  let total = estimateTokens(req.prompt ?? "");
+  if (req.system !== void 0) total += estimateTokens(req.system);
+  if (req.template !== void 0) total += estimateTokens(req.template);
+  if (req.images !== void 0) total += req.images.length * IMAGE_TOKEN_ESTIMATE;
+  return total;
+}
+function checkChatContext(req, options = {}) {
+  return check(estimateChatRequestTokens(req), req.options?.num_ctx, options);
+}
+function checkGenerateContext(req, options = {}) {
+  return check(estimateGenerateRequestTokens(req), req.options?.num_ctx, options);
+}
+function check(estimatedPromptTokens, requestNumCtx, options) {
+  const threshold = options.threshold ?? DEFAULT_CONTEXT_WARNING_THRESHOLD;
+  if (requestNumCtx !== void 0) {
+    return {
+      estimatedPromptTokens,
+      effectiveContextLength: requestNumCtx,
+      windowSource: "request",
+      exceedsThreshold: estimatedPromptTokens > requestNumCtx * threshold
+    };
+  }
+  if (options.defaultContextLength !== void 0) {
+    return {
+      estimatedPromptTokens,
+      effectiveContextLength: options.defaultContextLength,
+      windowSource: "client-default",
+      exceedsThreshold: estimatedPromptTokens > options.defaultContextLength * threshold
+    };
+  }
+  return {
+    estimatedPromptTokens,
+    effectiveContextLength: OLLAMA_FALLBACK_CONTEXT_LENGTH,
+    windowSource: "server-fallback",
+    exceedsThreshold: estimatedPromptTokens > OLLAMA_FALLBACK_CONTEXT_LENGTH
+  };
+}
+var OLLAMA_FALLBACK_CONTEXT_LENGTH = 2048;
+function contextWarningMessage(check2, kind) {
+  const where = `OllamaClient.${kind}()`;
+  const estimate = `~${check2.estimatedPromptTokens} tokens`;
+  if (check2.windowSource === "request") {
+    return `${where}: estimated prompt size ${estimate} is close to or beyond the request's context window (num_ctx=${check2.effectiveContextLength}). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`options.num_ctx\` or shorten the conversation. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+  }
+  if (check2.windowSource === "client-default") {
+    return `${where}: estimated prompt size ${estimate} is close to or beyond the client's \`defaultContextLength\` (${check2.effectiveContextLength}, injected as \`num_ctx\`). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`defaultContextLength\`, set \`options.num_ctx\` per request, or shorten the conversation. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+  }
+  return `${where}: estimated prompt size ${estimate} outright exceeds Ollama's conservative server-default context window (${OLLAMA_FALLBACK_CONTEXT_LENGTH}\u20134096 tokens when \`num_ctx\` is unset \u2014 model-dependent). Unless the model's default is larger, the server will silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Set \`options.num_ctx\` (or the client's \`defaultContextLength\`) to an explicit window to make truncation visible and controllable. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+}
+
+// src/context-discovery.ts
+function extractParameterNumCtx(parameters) {
+  if (!parameters) return void 0;
+  const match = /^[ \t]*num_ctx[ \t]+(\d+)\s*$/m.exec(parameters);
+  if (match === null) return void 0;
+  const value = Number.parseInt(match[1], 10);
+  return Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function findRunningModelContextLength(psModels, model) {
+  for (const entry of psModels) {
+    const exact = entry.name === model || entry.model === model;
+    const taglessPrefix = !model.includes(":") && (entry.name.startsWith(`${model}:`) || entry.model.startsWith(`${model}:`));
+    if (exact || taglessPrefix) {
+      return typeof entry.context_length === "number" && Number.isFinite(entry.context_length) && entry.context_length > 0 ? entry.context_length : void 0;
+    }
+  }
+  return void 0;
+}
+function positiveInt(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function resolveContextLength(signals) {
+  const running = positiveInt(signals.running);
+  const parameter = positiveInt(signals.parameter);
+  const native = positiveInt(signals.native);
+  if (running !== void 0) {
+    return {
+      contextLength: running,
+      source: "running",
+      ...parameter !== void 0 ? { parameterContextLength: parameter } : {},
+      ...native !== void 0 ? { nativeContextLength: native } : {},
+      runningContextLength: running
+    };
+  }
+  if (parameter !== void 0) {
+    return {
+      contextLength: parameter,
+      source: "parameters",
+      parameterContextLength: parameter,
+      ...native !== void 0 ? { nativeContextLength: native } : {}
+    };
+  }
+  if (native !== void 0) {
+    return { contextLength: native, source: "model-info", nativeContextLength: native };
+  }
+  return { contextLength: OLLAMA_FALLBACK_CONTEXT_LENGTH, source: "fallback" };
+}
+
 // src/keep-alive.ts
 var KEEP_ALIVE_UNLOAD = 0;
 var KEEP_ALIVE_INDEFINITE = -1;
@@ -2271,9 +2442,66 @@ var ModelsClient = class {
       { ...request, singleEndpoint: true }
     );
   }
-  ps() {
-    return this.runner((http) => http.request({ path: "/api/ps", method: "GET" }), {
-      singleEndpoint: true
+  ps(request) {
+    return this.runner(
+      (http, signal) => http.request({ path: "/api/ps", method: "GET", signal }),
+      {
+        singleEndpoint: true,
+        ...request?.signal !== void 0 ? { signal: request.signal } : {},
+        ...request?.timeoutMs !== void 0 ? { timeoutMs: request.timeoutMs } : {}
+      }
+    );
+  }
+  /**
+   * Discovers the model's real context window from the server — no more
+   * 2048/4096 guesswork. Consults, in precedence order:
+   *
+   *   1. `GET /api/ps` — the window the **running instance actually
+   *      allocated** (exact, reflects the Modelfile `num_ctx` default and
+   *      what fit in memory); skipped when the model isn't loaded, when
+   *      `skipRunningCheck` is set, or harmlessly on servers without the
+   *      field.
+   *   2. `POST /api/show` `parameters` — a Modelfile-authored
+   *      `num_ctx <n>` default, i.e. the window a cold load will allocate.
+   *   3. `POST /api/show` `model_info["<arch>.context_length"]` — the
+   *      model's **native GGUF maximum** (a ceiling to raise `num_ctx`
+   *      toward, not the allocated window).
+   *   4. Fallback — Ollama's conservative unset-`num_ctx` default (2048).
+   *
+   * The result carries every signal it found, so `nativeContextLength:
+   * 131072` vs `contextLength: 4096` (a 32× gap seen in the official API
+   * examples) is visible rather than guessed. Typical wiring:
+   *
+   * ```ts
+   * const { contextLength, source, nativeContextLength } =
+   *   await client.models.getContextLength({ model: 'gemma4' });
+   * // -> { contextLength: 4096, source: 'running', nativeContextLength: 131072 }
+   * ```
+   *
+   * Makes two server calls (`/api/ps` + `/api/show`) unless
+   * `skipRunningCheck` is set. A 404 from `/api/ps` (endpoint without the
+   * listing) is treated as "not running" and never fails the lookup;
+   * other transport errors propagate normally.
+   */
+  async getContextLength(request) {
+    let running;
+    if (request.skipRunningCheck !== true) {
+      try {
+        const ps = await this.ps({ signal: request.signal, timeoutMs: request.timeoutMs });
+        running = findRunningModelContextLength(ps.models, request.model);
+      } catch (err) {
+        if (!(err instanceof OllamaNotFoundError)) throw err;
+      }
+    }
+    const showRes = await this.show({
+      model: request.model,
+      signal: request.signal,
+      timeoutMs: request.timeoutMs
+    });
+    return resolveContextLength({
+      running,
+      parameter: extractParameterNumCtx(showRes.parameters),
+      native: extractContextLength(showRes.model_info)
     });
   }
   version() {
@@ -4271,6 +4499,52 @@ var ResponsesModule = class {
 };
 
 // src/conversation.ts
+function compactConversationHistory(messages, options) {
+  const reserve = Math.max(0, options.reserveForReply ?? 0);
+  const minTail = Math.max(0, options.minTailMessages ?? 2);
+  const budget = Math.max(0, options.maxEstimatedTokens - reserve);
+  let split = 0;
+  while (split < messages.length && messages[split].role === "system") split += 1;
+  const pinned = messages.slice(0, split);
+  const tail = messages.slice(split);
+  let used = 0;
+  for (const message of pinned) used += estimateMessageTokens(message);
+  const retained = [];
+  for (let i = tail.length - 1; i >= 0; i -= 1) {
+    const message = tail[i];
+    const cost = estimateMessageTokens(message);
+    const fits = used + cost <= budget;
+    if (!fits && retained.length >= minTail) break;
+    retained.unshift(message);
+    used += cost;
+  }
+  return [...pinned, ...retained];
+}
+function sanitizeHistoryForNextTurn(messages, options = {}) {
+  const keep = Math.max(0, options.keepImagesOnLastMessages ?? 1);
+  const placeholder = options.imagePlaceholder;
+  const cutoff = messages.length - keep;
+  const sanitized = [];
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index];
+    if (index >= cutoff || !message.images || message.images.length === 0) {
+      sanitized.push(message);
+      continue;
+    }
+    const { images: _evicted, ...rest } = message;
+    if (placeholder === void 0) {
+      sanitized.push(rest);
+    } else {
+      sanitized.push({
+        ...rest,
+        content: rest.content === "" ? placeholder : `${rest.content}
+
+${placeholder}`
+      });
+    }
+  }
+  return sanitized;
+}
 function extractTurnStats(res) {
   const cachedTokens = res.prompt_eval_cached_count ?? 0;
   const evaluatedTokens = res.prompt_eval_count ?? 0;
@@ -4357,6 +4631,48 @@ var ConversationSession = class {
   getMessages() {
     return this.history.map((message) => message);
   }
+  /**
+   * Compacts the session's history in place: pinned system prompt plus the
+   * most recent turns that fit the budget, oldest tailable turns dropped.
+   *
+   * This is the explicit escape hatch for sessions that outgrew their
+   * window — `cacheStats.hitRate` collapsing toward zero while history grows
+   * is the usual symptom, and the pre-flight warnings on `chat()` fire once
+   * the prompt estimate crosses the threshold. After compaction the next
+   * turn's prompt prefix differs from everything before it, so the KV cache
+   * starts cold — visible as a one-turn `evaluatedTokens` spike in
+   * `cacheStats`. Cumulative cache tallies are deliberately **not** reset:
+   * they are observations, and the spike is part of the story.
+   *
+   * Returns the before/after estimates and the drop count. No-op (zero
+   * drops, equal before/after estimates) when the history already fits.
+   */
+  compact(options = {}) {
+    const window = options.maxEstimatedTokens ?? this.config.options?.num_ctx ?? OLLAMA_FALLBACK_CONTEXT_LENGTH;
+    const reserve = options.reserveForReply ?? Math.ceil(window * 0.1);
+    const estimatedTokensBefore = this.history.reduce(
+      (sum, message) => sum + estimateMessageTokens(message),
+      0
+    );
+    const compacted = compactConversationHistory(this.history, {
+      maxEstimatedTokens: window,
+      reserveForReply: reserve,
+      ...options.minTailMessages !== void 0 ? { minTailMessages: options.minTailMessages } : {}
+    });
+    const estimatedTokensAfter = compacted.reduce(
+      (sum, message) => sum + estimateMessageTokens(message),
+      0
+    );
+    const droppedMessages = this.history.length - compacted.length;
+    this.history.length = 0;
+    this.history.push(...compacted);
+    return {
+      droppedMessages,
+      estimatedTokensBefore,
+      estimatedTokensAfter,
+      effectiveBudget: window - reserve
+    };
+  }
   /**
    * Clears the conversation back to its initial state (system prompt, zero
    * turns, zeroed cache statistics). The next turn starts with a cold cache
@@ -4375,103 +4691,6 @@ var ConversationSession = class {
   }
 };
 
-// src/context-safety.ts
-var DEFAULT_CONTEXT_WARNING_THRESHOLD = 0.9;
-var IMAGE_TOKEN_ESTIMATE = 300;
-var CHARS_PER_TOKEN = 4;
-function isCjkCodePoint(code) {
-  return code >= 19968 && code <= 40959 || // CJK Unified Ideographs
-  code >= 13312 && code <= 19903 || // CJK Extension A
-  code >= 12352 && code <= 12543 || // Hiragana + Katakana
-  code >= 44032 && code <= 55215 || // Hangul syllables
-  code >= 63744 && code <= 64255 || // CJK Compatibility Ideographs
-  code >= 65280 && code <= 65519;
-}
-function estimateTokens(text) {
-  if (text.length === 0) return 0;
-  let cjk = 0;
-  let other = 0;
-  for (const char of text) {
-    if (isCjkCodePoint(char.codePointAt(0) ?? 0)) cjk += 1;
-    else other += 1;
-  }
-  return Math.ceil(cjk + other / CHARS_PER_TOKEN);
-}
-var MESSAGE_OVERHEAD_TOKENS = 4;
-function estimateMessageTokens(message) {
-  let total = MESSAGE_OVERHEAD_TOKENS + estimateTokens(message.content ?? "");
-  if (message.thinking !== void 0) total += estimateTokens(message.thinking);
-  if (message.tool_calls !== void 0) {
-    for (const call of message.tool_calls) {
-      total += estimateTokens(call.function.name);
-      total += estimateTokens(JSON.stringify(call.function.arguments ?? {}));
-    }
-  }
-  if (message.images !== void 0) total += message.images.length * IMAGE_TOKEN_ESTIMATE;
-  return total;
-}
-function estimateChatRequestTokens(req) {
-  let total = 0;
-  for (const message of req.messages) total += estimateMessageTokens(message);
-  if (req.tools !== void 0) {
-    for (const tool of req.tools) {
-      total += estimateTokens(tool.function.description ?? "");
-      total += estimateTokens(JSON.stringify(tool.function.parameters ?? {}));
-    }
-  }
-  return total;
-}
-function estimateGenerateRequestTokens(req) {
-  let total = estimateTokens(req.prompt ?? "");
-  if (req.system !== void 0) total += estimateTokens(req.system);
-  if (req.template !== void 0) total += estimateTokens(req.template);
-  if (req.images !== void 0) total += req.images.length * IMAGE_TOKEN_ESTIMATE;
-  return total;
-}
-function checkChatContext(req, options = {}) {
-  return check(estimateChatRequestTokens(req), req.options?.num_ctx, options);
-}
-function checkGenerateContext(req, options = {}) {
-  return check(estimateGenerateRequestTokens(req), req.options?.num_ctx, options);
-}
-function check(estimatedPromptTokens, requestNumCtx, options) {
-  const threshold = options.threshold ?? DEFAULT_CONTEXT_WARNING_THRESHOLD;
-  if (requestNumCtx !== void 0) {
-    return {
-      estimatedPromptTokens,
-      effectiveContextLength: requestNumCtx,
-      windowSource: "request",
-      exceedsThreshold: estimatedPromptTokens > requestNumCtx * threshold
-    };
-  }
-  if (options.defaultContextLength !== void 0) {
-    return {
-      estimatedPromptTokens,
-      effectiveContextLength: options.defaultContextLength,
-      windowSource: "client-default",
-      exceedsThreshold: estimatedPromptTokens > options.defaultContextLength * threshold
-    };
-  }
-  return {
-    estimatedPromptTokens,
-    effectiveContextLength: OLLAMA_FALLBACK_CONTEXT_LENGTH,
-    windowSource: "server-fallback",
-    exceedsThreshold: estimatedPromptTokens > OLLAMA_FALLBACK_CONTEXT_LENGTH
-  };
-}
-var OLLAMA_FALLBACK_CONTEXT_LENGTH = 2048;
-function contextWarningMessage(check2, kind) {
-  const where = `OllamaClient.${kind}()`;
-  const estimate = `~${check2.estimatedPromptTokens} tokens`;
-  if (check2.windowSource === "request") {
-    return `${where}: estimated prompt size ${estimate} is close to or beyond the request's context window (num_ctx=${check2.effectiveContextLength}). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`options.num_ctx\` or shorten the conversation. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
-  }
-  if (check2.windowSource === "client-default") {
-    return `${where}: estimated prompt size ${estimate} is close to or beyond the client's \`defaultContextLength\` (${check2.effectiveContextLength}, injected as \`num_ctx\`). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`defaultContextLength\`, set \`options.num_ctx\` per request, or shorten the conversation. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
-  }
-  return `${where}: estimated prompt size ${estimate} outright exceeds Ollama's conservative server-default context window (${OLLAMA_FALLBACK_CONTEXT_LENGTH}\u20134096 tokens when \`num_ctx\` is unset \u2014 model-dependent). Unless the model's default is larger, the server will silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Set \`options.num_ctx\` (or the client's \`defaultContextLength\`) to an explicit window to make truncation visible and controllable. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
-}
-
 // src/embed-batch.ts
 var DEFAULT_EMBED_BATCH_SIZE = 32;
 var DEFAULT_EMBED_CONCURRENCY = 3;
@@ -5666,7 +5885,15 @@ var OllamaClient = class {
   createModel = (r) => this.models.create(r);
   deleteModel = (req) => this.models.delete(req);
   copyModel = (req) => this.models.copy(req);
-  ps = () => this.models.ps();
+  ps = (request) => this.models.ps(request);
+  /**
+   * Discovers the model's real context window — the allocated window of the
+   * running instance (`/api/ps`), the Modelfile `num_ctx` default, and the
+   * native GGUF maximum (`/api/show` `model_info`), resolved by precedence.
+   * Convenience alias for {@link ModelsClient.getContextLength} — see that
+   * method for the full contract and the precedence order.
+   */
+  getContextLength = (request) => this.models.getContextLength(request);
   version = () => this.models.version();
   createBlob = (digest, data) => this.models.createBlob(digest, data);
   checkBlob = (digest) => this.models.checkBlob(digest);
@@ -6914,11 +7141,29 @@ ${systemPrompt}`
 }
 
 // src/agent/agent.ts
+var SIGNATURE_REPORT_LIMIT = 200;
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+  const entries = Object.entries(value).filter(([, entryValue]) => entryValue !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+  return `{${entries.join(",")}}`;
+}
+function canonicalToolCallSignature(toolCall) {
+  return `${toolCall.function.name}(${stableStringify(toolCall.function.arguments)})`;
+}
+function reportableSignature(signature) {
+  return signature.length <= SIGNATURE_REPORT_LIMIT ? signature : `${signature.slice(0, SIGNATURE_REPORT_LIMIT)}\u2026`;
+}
 var Agent = class {
   client;
   tools;
   maxIterations;
   maxToolCalls;
+  maxRepeatedToolCalls;
   hooks;
   validateToolCapability;
   toolContextSize;
@@ -6927,10 +7172,14 @@ var Agent = class {
     this.tools = config.tools;
     this.maxIterations = config.maxIterations ?? 10;
     this.maxToolCalls = config.maxToolCalls;
+    this.maxRepeatedToolCalls = config.maxRepeatedToolCalls;
     this.hooks = config.hooks;
     if (this.maxToolCalls !== void 0 && (!Number.isInteger(this.maxToolCalls) || this.maxToolCalls < 0)) {
       throw new RangeError("Agent maxToolCalls must be a non-negative integer");
     }
+    if (this.maxRepeatedToolCalls !== void 0 && (!Number.isInteger(this.maxRepeatedToolCalls) || this.maxRepeatedToolCalls < 1)) {
+      throw new RangeError("Agent maxRepeatedToolCalls must be a positive integer");
+    }
     this.validateToolCapability = config.validateToolCapability ?? true;
     this.toolContextSize = config.toolContextSize ?? 32768;
     if (!Number.isInteger(this.toolContextSize) || this.toolContextSize <= 0) {
@@ -6977,6 +7226,7 @@ var Agent = class {
       )
     } : input.options;
     let toolCallsExecuted = 0;
+    const signatureCounts = /* @__PURE__ */ new Map();
     for (let iteration = 1; iteration <= this.maxIterations; iteration++) {
       const outcome = await withSpan(
         "ollama.agent.turn",
@@ -7008,6 +7258,24 @@ var Agent = class {
               { maxToolCalls: this.maxToolCalls, toolCallsExecuted }
             );
           }
+          if (this.maxRepeatedToolCalls !== void 0) {
+            for (const tc of toolCalls) {
+              const signature = canonicalToolCallSignature(tc);
+              const executions = (signatureCounts.get(signature) ?? 0) + 1;
+              if (executions > this.maxRepeatedToolCalls) {
+                throw new OllamaAgentToolLoopError(
+                  `Agent would repeat tool call "${tc.function.name}" ${executions} times (max ${this.maxRepeatedToolCalls}) without changing arguments \u2014 stuck in a tool loop`,
+                  {
+                    toolName: tc.function.name,
+                    repeatedExecutions: executions,
+                    maxRepeatedToolCalls: this.maxRepeatedToolCalls,
+                    signature: reportableSignature(signature)
+                  }
+                );
+              }
+              signatureCounts.set(signature, executions);
+            }
+          }
           for (const tc of toolCalls) {
             this.hooks?.onToolCallStart?.(tc);
           }
@@ -7040,6 +7308,160 @@ var Agent = class {
   }
 };
 
+// src/affinity.ts
+var DEFAULT_CONCURRENT_MODELS = 1;
+var DEFAULT_PER_MODEL_CONCURRENCY = 1;
+var DEFAULT_PS_CACHE_TTL_MS = 3e4;
+var ModelAffinityScheduler = class {
+  constructor(client, options = {}) {
+    this.client = client;
+    this.concurrentModels = options.concurrentModels ?? DEFAULT_CONCURRENT_MODELS;
+    this.perModelConcurrency = options.perModelConcurrency ?? DEFAULT_PER_MODEL_CONCURRENCY;
+    this.psCacheTtlMs = options.psCacheTtlMs ?? DEFAULT_PS_CACHE_TTL_MS;
+    if (!Number.isInteger(this.concurrentModels) || this.concurrentModels < 1) {
+      throw new OllamaClientError("concurrentModels must be an integer >= 1.", {
+        code: "invalid_request"
+      });
+    }
+    if (!Number.isInteger(this.perModelConcurrency) || this.perModelConcurrency < 1) {
+      throw new OllamaClientError("perModelConcurrency must be an integer >= 1.", {
+        code: "invalid_request"
+      });
+    }
+    if (!Number.isFinite(this.psCacheTtlMs) || this.psCacheTtlMs < 0) {
+      throw new OllamaClientError("psCacheTtlMs must be a non-negative number.", {
+        code: "invalid_request"
+      });
+    }
+  }
+  queues = /* @__PURE__ */ new Map();
+  concurrentModels;
+  perModelConcurrency;
+  psCacheTtlMs;
+  psCache;
+  drainWaiters = [];
+  /**
+   * Runs `task` on the scheduler, serialized per model. When `model` is a
+   * list of candidates, the already-loaded one is preferred (fresh
+   * `/api/ps` data subject to the TTL cache); with none loaded — or when the
+   * lookup fails — the first candidate runs. The chosen model is handed to
+   * the task.
+   */
+  async run(model, task) {
+    const candidates = typeof model === "string" ? [model] : [...model];
+    if (candidates.length === 0 || candidates.some((name) => typeof name !== "string" || name === "")) {
+      throw new OllamaClientError("run() requires at least one non-empty model name.", {
+        code: "invalid_request"
+      });
+    }
+    const chosen = candidates.length === 1 ? candidates[0] : await this.chooseCandidate(candidates);
+    return new Promise((resolve, reject) => {
+      const queue = this.queues.get(chosen) ?? { items: [], active: 0 };
+      this.queues.set(chosen, queue);
+      queue.items.push({
+        task,
+        resolve,
+        reject
+      });
+      this.pump();
+    });
+  }
+  /**
+   * Names of the models currently loaded, per `GET /api/ps`, cached for
+   * `psCacheTtlMs`. Degrades to an empty list when the server can't answer
+   * (never throws; candidate selection treats it as "nothing loaded").
+   */
+  async loadedModels() {
+    const names = await this.refreshPsNames();
+    return [...names];
+  }
+  /** Current scheduling state — active models and queued task count. */
+  get stats() {
+    const activeModels = [];
+    let queuedTasks = 0;
+    for (const [name, queue] of this.queues) {
+      if (queue.active > 0) activeModels.push(name);
+      queuedTasks += queue.items.length;
+    }
+    return { activeModels, queuedTasks };
+  }
+  /**
+   * Resolves once every queue is empty and no task is running. Does not
+   * abort anything — tasks are caller-owned; abort them via their own
+   * signals before disposing if needed.
+   */
+  async dispose() {
+    if (this.stats.queuedTasks === 0 && this.stats.activeModels.length === 0) return;
+    await new Promise((resolve) => {
+      this.drainWaiters.push(resolve);
+    });
+  }
+  async chooseCandidate(candidates) {
+    const loaded = await this.refreshPsNames();
+    for (const candidate of candidates) {
+      if (loaded.has(candidate)) return candidate;
+    }
+    return candidates[0];
+  }
+  async refreshPsNames() {
+    const now = Date.now();
+    if (this.psCache !== void 0 && now - this.psCache.at <= this.psCacheTtlMs) {
+      return this.psCache.names;
+    }
+    let names;
+    try {
+      const ps = await this.client.models.ps();
+      names = new Set(ps.models.map((entry) => entry.name));
+    } catch {
+      return /* @__PURE__ */ new Set();
+    }
+    this.psCache = { at: now, names };
+    return names;
+  }
+  pump() {
+    for (const [name, queue] of this.queues) {
+      while (queue.items.length > 0 && queue.active < this.perModelConcurrency) {
+        if (queue.active === 0 && this.activeModelCount() >= this.concurrentModels) {
+          break;
+        }
+        const entry = queue.items.shift();
+        queue.active += 1;
+        this.execute(name, queue, entry);
+      }
+    }
+  }
+  activeModelCount() {
+    let count = 0;
+    for (const queue of this.queues.values()) {
+      if (queue.active > 0) count += 1;
+    }
+    return count;
+  }
+  execute(name, queue, entry) {
+    void (async () => {
+      try {
+        entry.resolve(await entry.task(name));
+      } catch (err) {
+        entry.reject(err);
+      } finally {
+        queue.active -= 1;
+        if (queue.items.length === 0 && queue.active === 0) {
+          this.queues.delete(name);
+        }
+        if (this.stats.queuedTasks === 0 && this.stats.activeModels.length === 0) {
+          const waiters = [...this.drainWaiters];
+          this.drainWaiters.length = 0;
+          for (const resolve of waiters) resolve();
+        }
+        this.pump();
+      }
+    })();
+  }
+};
+function createModelAffinityScheduler(client, options) {
+  return new ModelAffinityScheduler(client, options);
+}
+
 // src/system-one.ts
 var MAX_SYSTEM_ONE_IMAGES_BYTES = 32 * 1024 * 1024;
 var MAX_SYSTEM_ONE_REQUEST_BYTES = 64 * 1024;
@@ -7047,6 +7469,6 @@ function estimateSystemOneRequestBytes(request) {
   return new TextEncoder().encode(JSON.stringify(request)).byteLength;
 }
 
-export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, Agent, AnthropicCompatClient, AnthropicMessagesStream, ConversationSession, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, IMAGE_TOKEN_ESTIMATE, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, McpBridge, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAgentMaxToolCallsError, OllamaAuthError, OllamaBadGatewayError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaIncompatibleModelError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaOverloadedError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaRequestTooLargeError, OllamaRequestValidationError, OllamaResponseValidationError, OllamaServerError, OllamaServerVersionUnknownError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaStreamError, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAIChatCompletionStream, OpenAICompatClient, OpenAICompletionStream, OpenAIResponsesStream, OpenAIResponsesStreamError, QuotaManager, RETRYABLE_STATUS_CODES, ResponsesModule, ToolCallAccumulator, ToolRegistry, addSpanEvent, applySkill, batchEmbed, calculateBackoff, checkChatContext, checkEndpointHealth, checkGenerateContext, composeMiddleware, contextWarningMessage, createConsoleLogger, createDecision, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateSystemOneRequestBytes, estimateTokens, extractUsage, fetchWithBackoff, findOversizedEmbedInputs, imageStringNeedsResolution, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mapError, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseSseStream, parseStructuredOutput, registerMcpTools, resolveCredentialEndpoints, resolveImageInput, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
+export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, Agent, AnthropicCompatClient, AnthropicMessagesStream, ConversationSession, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, IMAGE_TOKEN_ESTIMATE, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, ModelAffinityScheduler, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAgentMaxToolCallsError, OllamaAgentToolLoopError, OllamaAuthError, OllamaBadGatewayError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaIncompatibleModelError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaOverloadedError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaRequestTooLargeError, OllamaRequestValidationError, OllamaResponseValidationError, OllamaServerError, OllamaServerVersionUnknownError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaStreamError, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAIChatCompletionStream, OpenAICompatClient, OpenAICompletionStream, OpenAIResponsesStream, OpenAIResponsesStreamError, QuotaManager, RETRYABLE_STATUS_CODES, ResponsesModule, ToolCallAccumulator, ToolRegistry, addSpanEvent, applySkill, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, composeMiddleware, contextWarningMessage, createConsoleLogger, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, extractUsage, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, imageStringNeedsResolution, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mapError, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseSseStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, resolveImageInput, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map