micro-models-agent 2.11.0 → 2.12.0

package/dist/llm/openai-compat.js

@@ -6,14 +6,14 @@ import { LlmError } from "./llm-errors";
 import { backoffDelay } from "../utils/retry";
 import { StreamState } from "./stream-state";
 import { parseCacheUsage } from "./cache-usage";
-const REQUEST_TIMEOUT_MS = 120000;
-/** Max wait (ms) for a self-inflicted rate-limit slot before giving up. */
-const MAX_RATE_WAIT_MS = 30_000;
+import { LLM_REQUEST_TIMEOUT_MS as REQUEST_TIMEOUT_MS, LLM_MAX_RATE_WAIT_MS as MAX_RATE_WAIT_MS, } from "../config/timeouts";
+/** Cap completion-токенов в max_tokens, если конфиг не задал. */
+const DEFAULT_MAX_COMPLETION_TOKENS = 8192;
 /**
- * Client identity header. OpenCode Go asks clients to identify themselves with
- * their own user agent (not a generic SDK/HTTP-library name) so requests route
- * to coding-agent traffic. `readMmaVersion()` is memoized — every provider
- * construction would otherwise re-read package.json.
+ * Client identity-заголовок. OpenCode Go просит клиентов представляться своим
+ * user agent (не generic SDK/HTTP-библиотекой), чтобы запросы роутились в
+ * coding-agent трафик. `readMmaVersion()` мемоизирован — иначе каждая сборка
+ * провайдера перечитывала бы package.json.
  */
 let cachedUserAgent = null;
 function defaultUserAgent() {
@@ -21,6 +21,23 @@ function defaultUserAgent() {
         cachedUserAgent = `micro-models-agent/${readMmaVersion()}`;
     return cachedUserAgent;
 }
+/**
+ * Нормализует харнессный уровень reasoning под контракт провайдерского поля
+ * `reasoning_effort` (strict OpenAI/o-series принимает только
+ * low|medium|high). Иначе:
+ * - "default"/undefined → не шлём (решает провайдерский дефолт);
+ * - "none" → не шлём (strict OpenAI отвечает 400; отсутствие поля = не просим
+ *   повышать, а prompt-tag ещё и получает тег /no_think в `chat()`);
+ * - "max" → клампим к "high" (наибольшее валидное значение).
+ * Без нормализации неизвестное значение роняет ВЕСЬ запрос HTTP 400.
+ */
+function normalizeReasoningEffort(level) {
+    if (!level || level === "default" || level === "none")
+        return undefined;
+    if (level === "max")
+        return "high";
+    return level;
+}
 function buildRequestBody(opts) {
     const body = {
         model: opts.model,
@@ -37,21 +54,24 @@ function buildRequestBody(opts) {
         body.session_id = opts.sessionId;
     if (opts.stream && opts.streamUsage)
         body.stream_options = { include_usage: true };
-    // Apply reasoning effort via the provider's strategy
+    // Применяем effort через стратегию провайдера (уровень нормализуется под
+    // контракт OpenAI: low|medium|high).
     const strategy = opts.reasoningStrategy ?? "openai-effort";
-    const level = opts.reasoningEffort;
-    if (strategy === "openai-effort" && level && level !== "default") {
-        body.reasoning_effort = level;
+    const effort = normalizeReasoningEffort(opts.reasoningEffort);
+    if (strategy === "openai-effort") {
+        if (effort)
+            body.reasoning_effort = effort;
     }
     else if (strategy === "template-kwarg") {
-        body.chat_template_kwargs = { enable_thinking: level !== "none" };
+        body.chat_template_kwargs = { enable_thinking: opts.reasoningEffort !== "none" };
     }
-    else if (strategy === "prompt-tag" && level && level !== "default") {
-        // Send reasoning_effort in body (models that respect it via API) AND
-        // add /no_think tag to message (models that only respect prompt signals).
-        body.reasoning_effort = level;
+    else if (strategy === "prompt-tag") {
+        // Шлём reasoning_effort в теле (модели с API-поддержкой) И тег /no_think
+        // в сообщение (модели только с prompt-сигналами; тег ставит `chat()`).
+        if (effort)
+            body.reasoning_effort = effort;
     }
-    // "none" = unsupported, skip
+    // "none" = не поддерживается, пропуск
     if (opts.tools && opts.tools.length > 0) {
         body.tools = opts.tools.map((t) => ({
             type: "function",
@@ -65,6 +85,7 @@ function buildRequestBody(opts) {
     }
     return body;
 }
+/** Провайдер OpenAI-совместимого API (стрим + non-stream фолбэки, ретраи). */
 export class OpenAICompatProvider {
     model;
     contextWindow;
@@ -98,11 +119,16 @@ export class OpenAICompatProvider {
         this.userAgent = config.userAgent ?? defaultUserAgent();
         this.debug = config.logger ? config.logger.debug.bind(config.logger) : null;
     }
+    /**
+     * Стрим чата: rate-limit → стрим → фолбэк non-stream при пустом стриме.
+     * @param messages история; @param tools определения тулов;
+     * @param signal abort; @param options лимит токенов/reasoning.
+     * @returns асинхронный итератор чанков.
+     */
     async *chat(messages, tools, signal, options) {
-        // Check rate limit before making request. A self-inflicted limit should
-        // wait for a slot (bounded) instead of aborting a healthy turn; only if
-        // no slot frees within the window do we surface a recoverable error the
-        // agent loop can feed back (rather than dying).
+        // Проверка лимита до запроса. Собственный лимит ждёт слота (ограниченно),
+        // а не роняет здоровый ход; recoverable-ошибка наружу — только если слот
+        // не освободился в окне (цикл скормит её модели, а не умрёт).
         if (!this.rateLimiter.canMakeRequest()) {
             const waitMs = Math.min(this.rateLimiter.msUntilRequest(), MAX_RATE_WAIT_MS);
             if (waitMs > 0) {
@@ -112,9 +138,9 @@ export class OpenAICompatProvider {
                 throw new LlmError(`Rate limit exceeded: ${this.rateLimiter.getConfig().maxRequestsPerMinute} requests per minute`, { recoverable: true });
             }
         }
-        // Record this request
+        // Фиксируем запрос
         this.rateLimiter.recordRequest();
-        // Apply prompt-tag strategy: append /no_think to last user message (outgoing copy only)
+        // Prompt-tag стратегия: дописать /no_think в последнее user-сообщение (только исходящая копия)
         let effectiveMessages = messages;
         if (options?.reasoningStrategy === "prompt-tag" && options?.reasoningEffort === "none") {
             effectiveMessages = this.applyPromptTag(messages, "/no_think");
@@ -132,12 +158,11 @@ export class OpenAICompatProvider {
                 hasReasoning = true;
             yield chunk;
         }
-        // A stream that ended with reasoning but no text/tool_call means the model
-        // THOUGHT but never produced an answer (observed: qwen3.5-9b in LM Studio
-        // emits reasoning_content then stops). The streamed reasoning was already
-        // delivered; fetch the missing answer via non-streaming. The fallback's
-        // own reasoning chunk is dropped so thinking is not shown twice — no text
-        // was emitted, so there is no duplicate-answer risk.
+        // Стрим кончился на reasoning без текста/tool_call: модель ПОДУМАЛА, но
+        // ответа не дала (наблюдалось: qwen3.5-9b в LM Studio шлёт reasoning_content
+        // и встаёт). Reasoning уже отдан; недостающий ответ добираем non-stream.
+        // Reasoning-чанк фолбэка дропаем, чтобы не показать дважды — текста не было,
+        // риск дубля ответа отсутствует.
         if (!hasToolCall && !hasText) {
             this.debug?.("LLM streaming produced no text/tool_call — falling back to non-streaming");
             const fallback = await this.doNonStreaming(effectiveMessages, tools, signal, options);
@@ -149,17 +174,17 @@ export class OpenAICompatProvider {
             }
         }
     }
-    /** Append a tag to the last user message (outgoing copy, never stored in context). */
+    /** Дописывает тег в последнее user-сообщение (исходящая копия, не в контекст). */
     applyPromptTag(messages, tag) {
         const copy = [...messages];
         for (let i = copy.length - 1; i >= 0; i--) {
             if (copy[i].role === "user") {
                 const msg = { ...copy[i] };
                 if (typeof msg.content === "string") {
-                    msg.content = msg.content + "\n" + tag;
+                    msg.content = `${msg.content}\n${tag}`;
                 }
                 else {
-                    // Array of parts — append a text part
+                    // Массив частей — дописываем текстовую часть
                     msg.content = [...msg.content, { type: "text", text: tag }];
                 }
                 copy[i] = msg;
@@ -172,6 +197,7 @@ export class OpenAICompatProvider {
         const { baseDelay, maxDelay, maxStreamRetries, noDataTimeoutMs } = this.retryConfig;
         const streamRetries = maxStreamRetries ?? 2;
         const idleTimeoutMs = noDataTimeoutMs ?? 180000;
+        let usedNonStreamingFallback = false;
         for (let attempt = 0;; attempt++) {
             let emitted = false;
             const onEmit = () => {
@@ -179,27 +205,44 @@ export class OpenAICompatProvider {
             };
             try {
                 const sawDone = yield* this.streamOnce(messages, tools, signal, options, onEmit, idleTimeoutMs);
-                // Clean [DONE] or any partial content → deliver what we have.
+                // Чистый [DONE] или частичный контент — отдаём что есть.
                 if (sawDone || emitted)
                     return;
-                // Stream closed before [DONE] with zero content → retryable truncation.
+                // Стрим закрылся до [DONE] с нулевым контентом — ретраябельная обрезка.
                 if (attempt >= streamRetries)
                     return;
             }
             catch (err) {
                 if (err?.name === "AbortError" || (err instanceof LlmError && err.terminal) || signal?.aborted)
                     throw err;
-                // Content was already delivered — a re-stream would duplicate chunks.
+                // Stall буферизованного SSE после tool_call-дельт: один раз переспрашиваем
+                // non-stream. Стрим тут — битый путь, повтор тем же способом снова
+                // встанет; а tool_call агент получить обязан.
+                if (err?.stalledAfterToolCall === true && !usedNonStreamingFallback) {
+                    usedNonStreamingFallback = true;
+                    this.debug?.("LLM stream stalled after tool_call — falling back to non-streaming request");
+                    const fallback = await this.doNonStreaming(messages, tools, signal, options);
+                    this.debug?.("LLM non-streaming fallback result", { chunks: fallback.length });
+                    for (const chunk of fallback) {
+                        // Reasoning до stall уже, вероятно, устримлен; копию фолбэка дропаем,
+                        // чтобы не дублировать мышление.
+                        if (chunk.type === "reasoning")
+                            continue;
+                        yield chunk;
+                    }
+                    return;
+                }
+                // Контент уже отдан — перестрим продублировал бы чанки.
                 if (emitted || attempt >= streamRetries)
                     throw err;
-                // Connection dropped before any content → retry the whole request.
+                // Обрыв до любого контента — переспрашиваем целиком.
             }
             // Экспоненциальный backoff с джиттером (общий хелпер из src/utils).
             await this.sleep(backoffDelay(attempt, baseDelay, maxDelay, 0.1), signal);
         }
     }
     async *streamOnce(messages, tools, signal, options, onEmit, idleTimeoutMs) {
-        const maxTokens = options?.maxTokens ?? this.config.maxCompletionTokens ?? 4096;
+        const maxTokens = options?.maxTokens ?? this.config.maxCompletionTokens ?? DEFAULT_MAX_COMPLETION_TOKENS;
         const body = buildRequestBody({
             model: this.model,
             messages,
@@ -231,8 +274,8 @@ export class OpenAICompatProvider {
             });
         }
         catch (err) {
-            // Fetch-level failures are already HTTP-retried inside fetchWithRetry —
-            // don't double-retry them at the stream level.
+            // Fetch-сбои уже HTTP-ретраятся внутри fetchWithRetry —
+            // на уровне стрима повторно не ретраим.
             if (err?.name === "AbortError")
                 throw err;
             const wrapped = err instanceof Error ? err : new Error(String(err));
@@ -266,6 +309,14 @@ export class OpenAICompatProvider {
         const toolCallAccs = new Map();
         // Единый контейнер состояния стрима (вместо 9 разрозненных флагов).
         const st = new StreamState();
+        // Stall после старта tool_call-дельт обычно значит: провайдер буферизует
+        // SSE вместо стрима дельт аргументов (видели на LM Studio). Помечаем ошибку,
+        // чтобы `doStream` переспросил non-stream вместо провала всего прогона.
+        const idleError = () => {
+            const e = new Error(t(st.sawToolCallStart ? "error.llm_stream_idle_toolcall" : "error.llm_stream_idle", { timeout: idleTimeoutMs }));
+            e.stalledAfterToolCall = st.sawToolCallStart;
+            return e;
+        };
         const readIdle = () => new Promise((resolve, reject) => {
             const idleTimer = setTimeout(() => {
                 flagTimeout();
@@ -274,13 +325,13 @@ export class OpenAICompatProvider {
             reader.read().then((result) => {
                 clearTimeout(idleTimer);
                 if (isTimeout())
-                    reject(new Error(t(st.sawToolCallStart ? "error.llm_stream_idle_toolcall" : "error.llm_stream_idle", { timeout: idleTimeoutMs })));
+                    reject(idleError());
                 else
                     resolve(result);
             }, (err) => {
                 clearTimeout(idleTimer);
                 if (isTimeout())
-                    reject(new Error(t(st.sawToolCallStart ? "error.llm_stream_idle_toolcall" : "error.llm_stream_idle", { timeout: idleTimeoutMs })));
+                    reject(idleError());
                 else
                     reject(err);
             });
@@ -306,10 +357,9 @@ export class OpenAICompatProvider {
                         }
                     }
                     else {
-                        // Not SSE-framed — Ollama (and some other backends) may stream
-                        // NDJSON or send mid-stream errors as bare JSON. Try to parse the
-                        // raw line; unparseable noise (SSE comments, keep-alives) is
-                        // counted and skipped.
+                        // Не SSE-фрейм — Ollama (и часть бэкендов) стримят NDJSON или шлют
+                        // mid-stream ошибки голым JSON. Пробуем парсить сырую строку;
+                        // непарсящийся шум (SSE-комменты, keep-alive) считаем и пропускаем.
                         st.nonDataLines++;
                         if (st.nonDataSamples.length < 5)
                             st.nonDataSamples.push(trimmed.slice(0, 200));
@@ -320,7 +370,7 @@ export class OpenAICompatProvider {
                         st.parsedChunks++;
                         const choice = parsed.choices?.[0];
                         if (!choice) {
-                            // Usage comes in the last chunk with empty choices
+                            // Usage приходит в последнем чанке с пустыми choices
                             if (parsed.usage) {
                                 st.usage = {
                                     promptTokens: parsed.usage.prompt_tokens ?? 0,
@@ -331,14 +381,14 @@ export class OpenAICompatProvider {
                                 this.debug?.("LLM stream usage", { ...st.usage });
                             }
                             else if (parsed.error) {
-                                // Mid-stream provider error (Ollama sends {"error": "..."} as
-                                // bare JSON once generation already started). Surface it —
-                                // swallowing it makes the response look silently empty.
-                                // Thrown OUTSIDE the JSON-parse try/catch below.
+                                // Mid-stream ошибка провайдера (Ollama шлёт {"error": "..."}
+                                // голым JSON после старта генерации). Показываем — глотание
+                                // даст молча пустой ответ.
+                                // Брошено ВНЕ try/catch JSON-парсинга ниже.
                                 st.midStreamError = String(parsed.error);
                             }
-                            // NOTE: no `continue` here — it would skip the midStreamError
-                            // throw below (which lives outside this try/catch).
+                            // NOTE: `continue` тут нет — он пропустил бы throw midStreamError
+                            // ниже (он вне этого try/catch).
                         }
                         else {
                             if (st.parsedChunks <= 3 || st.parsedChunks % 50 === 0) {
@@ -353,7 +403,7 @@ export class OpenAICompatProvider {
                             const finishReason = choice.finish_reason;
                             if (finishReason)
                                 st.lastFinishReason = finishReason;
-                            // `reasoning` is the Ollama alias for OpenAI's `reasoning_content`.
+                            // `reasoning` — алиас Ollama для openai-`reasoning_content`.
                             const reasoningDelta = delta.reasoning_content ?? delta.reasoning;
                             if (reasoningDelta) {
                                 onEmit();
@@ -400,7 +450,7 @@ export class OpenAICompatProvider {
                         }
                     }
                     catch {
-                        // Skip malformed JSON lines
+                        // Битые JSON-строки пропускаем
                     }
                     if (st.midStreamError) {
                         throw new Error(t("error.llm_provider_stream_error", { error: st.midStreamError.slice(0, 300) }));
@@ -411,10 +461,10 @@ export class OpenAICompatProvider {
                 onEmit();
                 yield { type: "done", usage: st.usage };
             }
-            // finish_reason "length": the completion hit the token limit. An
-            // unfinished tool_call would otherwise be silently swallowed (tool_calls
-            // are only yielded on finish_reason "tool_calls") and surface as an
-            // empty response → blind hallucination retries. Surface the real cause.
+            // finish_reason "length": completion упёрся в лимит токенов. Незаконченный
+            // tool_call иначе молча глотается (tool_calls отдаются только на
+            // finish_reason "tool_calls") и всплывает пустым ответом → слепые
+            // hallucination-ретраи. Показываем настоящую причину.
             if (st.lastFinishReason === "length") {
                 const truncatedToolCall = st.sawToolCallStart && toolCallAccs.size > 0;
                 if (truncatedToolCall || !st.sawText) {
@@ -454,14 +504,14 @@ export class OpenAICompatProvider {
             streamUsage: this.cache?.requestStreamUsage === true,
         };
     }
-    /** Shared request setup: auth headers + timeout/abort controller wiring. */
+    /** Общая подготовка запроса: auth-заголовки + таймаут/abort-контроллер. */
     buildRequestSetup(signal) {
         const headers = {
             "Content-Type": "application/json",
             "User-Agent": this.userAgent,
         };
         if (this.config.apiKey && this.config.apiKey !== "not-needed") {
-            headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+            headers.Authorization = `Bearer ${this.config.apiKey}`;
         }
         const sessionId = this.getSessionId?.();
         // Когда capability задана — шлём заголовок только тем, кому он нужен
@@ -500,7 +550,7 @@ export class OpenAICompatProvider {
         };
     }
     async doNonStreaming(messages, tools, signal, options) {
-        const maxTokens = options?.maxTokens ?? this.config.maxCompletionTokens ?? 4096;
+        const maxTokens = options?.maxTokens ?? this.config.maxCompletionTokens ?? DEFAULT_MAX_COMPLETION_TOKENS;
         const body = buildRequestBody({
             model: this.model,
             messages,
@@ -528,7 +578,7 @@ export class OpenAICompatProvider {
                 }));
             }
             const data = await response.json();
-            // Some backends (e.g. Ollama) return HTTP 200 with {"error": "..."}.
+            // Часть бэкендов (напр. Ollama) отдают HTTP 200 с {"error": "..."}.
             if (data.error && !data.choices) {
                 throw new Error(t("error.llm_provider_stream_error", { error: String(data.error).slice(0, 300) }));
             }
@@ -557,15 +607,15 @@ export class OpenAICompatProvider {
                     });
                 }
             }
-            // Completed text but hit the cap: surface a visible warning instead of
-            // silently accepting a cut-off answer (see the streaming path).
+            // Текст готов, но упёрся в cap: видимый warning вместо молча
+            // принятого обрезанного ответа (см. стрим-путь).
             if (choice.finish_reason === "length" && msg.content && !msg.tool_calls) {
                 chunks.push({
                     type: "warning",
                     content: t("error.llm_output_truncated", { tokens: maxTokens }),
                 });
             }
-            // Append usage from API response
+            // Дописываем usage из ответа API
             if (data.usage) {
                 chunks.push({
                     type: "done",
@@ -589,9 +639,17 @@ export class OpenAICompatProvider {
             cleanup();
         }
     }
+    /**
+     * Считает токены текста (tiktoken по дефолтной модели).
+     * @param text текст; @returns число токенов.
+     */
     countTokens(text) {
         return this.tokenCounter.count(text);
     }
+    /**
+     * Список моделей провайдера (`/models`: id/name/model).
+     * @returns имена моделей; @throws при недоступности провайдера.
+     */
     async listModels() {
         try {
             const url = `${this.config.baseUrl.replace(/\/+$/, "")}/models`;
@@ -600,20 +658,35 @@ export class OpenAICompatProvider {
                 "User-Agent": this.userAgent,
             };
             if (this.config.apiKey && this.config.apiKey !== "not-needed") {
-                headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+                headers.Authorization = `Bearer ${this.config.apiKey}`;
             }
             const response = await fetch(url, {
                 method: "GET",
                 headers,
             });
             if (!response.ok) {
-                // Surface the failure: health probes must distinguish a dead
-                // provider from one that serves an empty model list.
+                // Провал наружу: health-пробы должны отличать мёртвый провайдер
+                // от пустого списка моделей.
                 throw new Error(`HTTP ${response.status} from ${url}`);
             }
-            const data = (await response.json());
-            const models = (data.data || data || [])
-                .map((m) => m.id || m.name || m.model || "")
+            const data = await response.json();
+            const rawList = Array.isArray(data)
+                ? data
+                : data && typeof data === "object" && Array.isArray(data.data)
+                    ? data.data
+                    : [];
+            const models = rawList
+                .map((m) => {
+                if (m && typeof m === "object") {
+                    const obj = m;
+                    for (const key of ["id", "name", "model"]) {
+                        const v = obj[key];
+                        if (typeof v === "string" && v)
+                            return v;
+                    }
+                }
+                return "";
+            })
                 .filter(Boolean);
             return models;
         }
@@ -643,8 +716,8 @@ export class OpenAICompatProvider {
                     throw err;
             }
             if (attempt < maxRetries) {
-                // Prefer the provider's Retry-After window (saturating at maxDelay);
-                // otherwise exponential backoff. 429s from free tiers need a real wait.
+                // Приоритет окну Retry-After провайдера (cap на maxDelay); иначе —
+                // экспоненциальный backoff. 429 с free-тарифов требуют реального ожидания.
                 const delay = lastRetryAfter > 0
                     ? Math.min(lastRetryAfter, maxDelay)
                     : backoffDelay(attempt, baseDelay, maxDelay, 0.1);

package/dist/llm/orchestrator.js

@@ -85,8 +85,9 @@ Respond with JSON only (no markdown fences):
 or
 {"action": "reject", "explanation": "why"}`;
 const DEFAULT_BASE_URL = "http://localhost:1234/v1";
-/** Fallback context window when neither the provider entry nor the config sets one. */
+/** Запасное окно контекста, если ни запись провайдера, ни конфиг его не задают. */
 const DEFAULT_ORCH_CONTEXT_WINDOW = 32768;
+/** Клиент оркестратора: строит план, сливает результаты, роутит scope-запросы. */
 export class OrchestratorClient {
     config;
     provider = null;
@@ -110,11 +111,10 @@ export class OrchestratorClient {
         }
     }
     /**
-     * Build the orchestrator provider through ProviderManager so per-entry
-     * contextWindow/retry/rateLimits and failover entries are honored
-     * (legacy {type,baseUrl,apiKey} configs are normalized by the manager).
-     * Previously the provider was built directly with a hardcoded 32768 window
-     * and no retry/rate-limit/failover support at all.
+     * Строит провайдер оркестратора через ProviderManager: учитываются
+     * per-entry contextWindow/retry/rateLimits и failover-записи (легаси
+     * {type,baseUrl,apiKey} менеджер нормализует). Раньше провайдер строился
+     * напрямую с хардкодом окна 32768 — без ретраев/лимитов/failover вовсе.
      */
     buildManagedProvider(config) {
         const providerCfg = config.provider;
@@ -134,6 +134,10 @@ export class OrchestratorClient {
         }
         return provider;
     }
+    /**
+     * Включён ли оркестратор (задана ли модель).
+     * @returns true, если провайдер построен.
+     */
     isEnabled() {
         return this.provider !== null;
     }
@@ -171,6 +175,11 @@ export class OrchestratorClient {
             }
         }
     }
+    /**
+     * Строит MoE-план из задачи пользователя.
+     * @param userPrompt задача; @param _context неиспользуемый контекст;
+     * @returns план с сырым ответом либо ошибку.
+     */
     async plan(userPrompt, _context, signal) {
         if (!this.provider)
             return { error: "Orchestrator not enabled — no orchestrator model configured" };
@@ -180,11 +189,16 @@ export class OrchestratorClient {
         ];
         const text = await this.chat(messages, signal);
         const parsed = this.parseJSON(text);
-        if (parsed && parsed.subtasks && parsed.subtasks.length > 0) {
+        if (parsed?.subtasks && parsed.subtasks.length > 0) {
             return { plan: parsed, raw: text };
         }
         return { error: `Failed to parse plan from LLM output. Raw: ${text.slice(0, 500)}` };
     }
+    /**
+     * Сливает результаты сабтасков: финал либо запрос re-plan.
+     * @param input план, результаты, ошибки/варнинги верификатора;
+     * @returns финал с ответом либо replan с обновлённым планом.
+     */
     async verifyAndMerge(input, signal) {
         if (!this.provider)
             return { type: "final", finalAnswer: input.results.map((r) => r.summary).join("\n") };
@@ -195,7 +209,7 @@ export class OrchestratorClient {
         ];
         const text = await this.chat(messages, signal);
         const parsed = this.parseJSON(text);
-        if (parsed && parsed.type) {
+        if (parsed?.type) {
             return parsed;
         }
         return {
@@ -205,8 +219,8 @@ export class OrchestratorClient {
         };
     }
     /**
-     * Router decision on a sub-agent's scope request. Defaults to reject on any
-     * parse failure — scope must never expand silently.
+     * Решение роутера по scope-запросу субагента. Дефолт на любой ошибке
+     * парсинга — reject: scope молча не расширяется никогда.
      */
     async resolveScopeRequest(subtaskId, request, signal) {
         if (!this.provider)
@@ -223,7 +237,7 @@ export class OrchestratorClient {
         if (parsed && parsed.action === "approve") {
             const write = Array.isArray(parsed.write) ? parsed.write.map(String) : [];
             const read = Array.isArray(parsed.read) ? parsed.read.map(String) : [];
-            // An approve without any concrete files is meaningless — treat as reject.
+            // Approve без конкретных файлов бессмыслен — считаем reject.
             if (write.length === 0 && read.length === 0) {
                 return { action: "reject", explanation: "approve carried no files" };
             }
@@ -236,6 +250,10 @@ export class OrchestratorClient {
                 : `unparseable router decision: ${text.slice(0, 200)}`,
         };
     }
+    /**
+     * Строит простой план-список шагов (легаси-поверхность).
+     * @param task задача; @returns шаги плана (фолбэк — сама задача).
+     */
     async createPlan(task) {
         if (!this.provider)
             throw new Error("Orchestrator not enabled");
@@ -252,6 +270,10 @@ export class OrchestratorClient {
             return parsed;
         return { steps: [task] };
     }
+    /**
+     * Рекомендует путь разрешения конфликта.
+     * @param context описание ситуации; @returns рекомендация текстом.
+     */
     async resolveConflict(context) {
         if (!this.provider)
             throw new Error("Orchestrator not enabled");

package/dist/llm/provider-budget.js

@@ -1,10 +1,10 @@
-// src/llm/provider-budget
+/** Баланс провайдера: запрос расхода/остатка (только OpenRouter по API). */
 /**
  * Запрос баланса/расхода у провайдера. Поддерживается только OpenRouter —
  * единственный, кто отдаёт эти данные по API-ключу. Zen/Go баланс не
  * возвращают (только веб-дашборд), поэтому для них честно `unsupported`.
  */
-const DEFAULT_TIMEOUT_MS = 5000;
+import { PROVIDER_BUDGET_TIMEOUT_MS as DEFAULT_TIMEOUT_MS } from "../config/timeouts";
 /** Приводит значение к конечному числу; иначе undefined. */
 function num(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;