micro-models-agent 0.63.0 → 1.1.0

package/dist/core/agent/compaction.js

@@ -0,0 +1,89 @@
+import { FORCED_COMPACTION_COOLDOWN, QUALITY_TRIGGER_THRESHOLD } from "./constants";
+/**
+ * Единая точка компакции контекста. В agent.ts логика дублировалась в 4 местах:
+ * 1) интервал (needsCompaction) в начале итерации;
+ * 2) принудительно по низкому качеству (< QUALITY_TRIGGER_THRESHOLD) с cooldown;
+ * 3) принудительно по переполнению бюджета истории;
+ * 4) после добавления результата тула.
+ *
+ * Все четыре консолидированы здесь и выполняют одинаковый контракт:
+ * компакция → логирование в session log → обогащение детектора халлюцинаций
+ * известными файлами из сводки.
+ */
+export class CompactionService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Пре-итерационные проверки: интервал → качество → переполнение.
+     * Порядок сохранён из оригинального цикла: каждая следующая проверка
+     * видит контекст уже ПОСЛЕ предыдущей компакции.
+     */
+    compactIfNeeded(state) {
+        this.compactOnInterval(state.iteration);
+        this.compactOnQuality(state);
+        this.compactOnOverflow(state.iteration);
+    }
+    /** Проверка после добавления результата тула в контекст. */
+    compactAfterTool(state) {
+        const { contextManager } = this.deps;
+        if (!contextManager.needsCompaction())
+            return;
+        const result = contextManager.compact();
+        if (!result)
+            return;
+        this.deps.logger.debug("Context compacted after tool result");
+        this.deps.slog.logCompaction({ reason: "after_tool", iteration: state.iteration, ...result });
+        this.deps.hallucinationDetector.addKnownFiles(contextManager.getKnownFiles());
+    }
+    compactOnInterval(iteration) {
+        const { contextManager } = this.deps;
+        if (!contextManager.needsCompaction())
+            return;
+        const result = contextManager.compact();
+        if (!result)
+            return;
+        this.deps.logger.debug("Context compacted");
+        this.deps.slog.logCompaction({ reason: "interval", iteration, ...result });
+        this.deps.hallucinationDetector.addKnownFiles(contextManager.getKnownFiles());
+    }
+    compactOnQuality(state) {
+        const { contextManager } = this.deps;
+        const iteration = state.iteration;
+        const quality = contextManager.getQuality();
+        const cooldownElapsed = iteration - state.lastForcedCompactionIteration >= FORCED_COMPACTION_COOLDOWN;
+        if (quality < QUALITY_TRIGGER_THRESHOLD &&
+            contextManager.getCompactionCount() > 0 &&
+            cooldownElapsed) {
+            state.lastForcedCompactionIteration = iteration;
+            const result = contextManager.compact();
+            if (!result)
+                return;
+            this.deps.logger.warn(`Low context quality (${quality}%) — forced compaction`);
+            this.deps.slog.logCompaction({
+                reason: `quality-triggered (${quality}% < ${QUALITY_TRIGGER_THRESHOLD}%)`,
+                iteration,
+                ...result,
+            });
+            this.deps.hallucinationDetector.addKnownFiles(contextManager.getKnownFiles());
+        }
+    }
+    compactOnOverflow(iteration) {
+        const { contextManager } = this.deps;
+        const currentTokens = contextManager.getEstimatedTokens();
+        const budget = contextManager.getBudget();
+        if (currentTokens <= budget.history)
+            return;
+        const result = contextManager.compact();
+        if (!result)
+            return;
+        this.deps.logger.warn(`Context overflow (${currentTokens} > ${budget.history}), forced compaction`);
+        this.deps.slog.logCompaction({
+            reason: `overflow (${currentTokens} > ${budget.history})`,
+            iteration,
+            ...result,
+        });
+        this.deps.hallucinationDetector.addKnownFiles(contextManager.getKnownFiles());
+    }
+}

package/dist/core/agent/constants.js

@@ -0,0 +1,61 @@
+/**
+ * Константы агентного цикла. Вынесены из agent.ts, чтобы:
+ * 1) не растекаться магическими числами по модулям;
+ * 2) быть переиспользуемыми между extracted-модулями (compaction, tool-batch и т.д.);
+ * 3) каждая константа несёт JSDoc с обоснованием значения.
+ */
+/** Макс. доля бюджета истории под результат одного тула (по токенам). */
+export const TOOL_RESULT_MAX_TOKENS_RATIO = 0.3;
+/** Абсолютный потолок результата тула в символах. */
+export const TOOL_RESULT_ABSOLUTE_MAX_CHARS = 15000;
+/**
+ * Порог качества контекста, ниже которого включается принудительная
+ * компакция. См. FORCED_COMPACTION_COOLDOWN — без cooldown низкое
+ * качество ретриггерит компакцию на каждой итерации.
+ */
+export const QUALITY_TRIGGER_THRESHOLD = 40;
+/**
+ * Макс. символов аргументов тула в <system-summary>. Не допускает
+ * дублирования `content` из write_file поверх role:"tool" сообщения,
+ * которое уже несёт результат.
+ */
+export const TOOL_ARGS_SUMMARY_MAX_CHARS = 240;
+/**
+ * Мин. число итераций между принудительными компакциями по качеству.
+ * Без него компакция не может восстановить качество и выжигает весь
+ * бюджет на компактирование (наблюдалось: 56 компакций за ~28 минут).
+ */
+export const FORCED_COMPACTION_COOLDOWN = 3;
+/** Макс. повторов при восстановимой ошибке LLM (например, токен-лимит). */
+export const MAX_LLM_ERROR_RETRIES = 2;
+/** Макс. повторов при вердикте халлюцинации "retry". */
+export const MAX_HALLUCINATION_RETRIES = 3;
+/** Порог подряд идущих неудач тулов до сообщения о восстановлении. */
+export const MAX_CONSECUTIVE_TOOL_FAILURES = 5;
+/**
+ * Мин. общих (не подряд идущих) неудач тула до записи правила в память.
+ * Фиксирует системные проблемы (ENOENT у LSP, сломанный конфиг), которые
+ * не всплывают по пути "5 подряд неудач".
+ */
+export const MIN_REPEATED_TOOL_FAILURES = 3;
+/** Макс. повторов финального аудита. */
+export const MAX_AUDIT_RETRIES = 3;
+/** Макс. повторов пустого ответа. */
+export const MAX_EMPTY_RESPONSE_RETRIES = 2;
+/** Макс. повторных одинаковых тулов в режиме exit-on-complete. */
+export const MAX_REPEATED_TOOL_CALLS = 2;
+/**
+ * Макс. повторных одинаковых тулов в интерактивном режиме до жёсткой
+ * остановки. Выше, чем в exit-on-complete: сначала модель получает nudge
+ * (по одному разу на каждый повтор), и только потом цикл обрывается —
+ * без этого модель, игнорирующая подсказки, бесконечно повторяет один
+ * и тот же вызов (наблюдалось: session_info подряд после завершения задачи).
+ */
+export const MAX_REPEATED_TOOL_CALLS_INTERACTIVE = 5;
+/**
+ * Порог цикла «перфекционизм»: столько правок одного файла (или запусков
+ * одной команды) за прогон, после которых цикл подталкивает модель закрыть
+ * задачу. Наблюдение ses_mthn3c2a: задача готова на итерации 13, модель ещё
+ * 20+ итераций микроредактировала один файл (edit → build → read → edit…).
+ */
+export const MUTATION_CYCLE_NUDGE_THRESHOLD = 5;

package/dist/core/agent/context-renderer.js

@@ -0,0 +1,40 @@
+import { pc } from "../../ui/colors";
+/**
+ * Рендер UI-индикаторов контекста (stats-бар и уведомление о компакции).
+ *
+ * Вынесен из agent.ts, где рендеринг жил прямо в бизнес-логике цикла.
+ * `lastCompactionShown` хранится внутри и переживает несколько запусков
+ * цикла (как исходное поле Agent) — экземпляр должен быть полем класса,
+ * а не создаваться заново на каждый ход.
+ */
+export class ContextRenderer {
+    lastCompactionShown = 0;
+    render(ui, contextManager, onMeta) {
+        if (ui?.showContextStats) {
+            this.renderStats(contextManager, onMeta);
+        }
+        else if (ui?.showCompaction) {
+            this.renderCompaction(contextManager, onMeta);
+        }
+    }
+    renderStats(contextManager, onMeta) {
+        const ctxTokens = contextManager.getEstimatedTokens();
+        const ctxBudget = contextManager.getBudget();
+        const ctxPct = Math.min(100, Math.round((ctxTokens / ctxBudget.history) * 100));
+        const barLen = 10;
+        const filled = Math.round((ctxPct / 100) * barLen);
+        const ctxBar = pc.green("█".repeat(filled)) + pc.dim("░".repeat(barLen - filled));
+        const pctColor = ctxPct >= 75 ? pc.yellow : pc.dim;
+        const compCount = contextManager.getCompactionCount();
+        const quality = contextManager.getQuality();
+        const qualityColor = quality >= 70 ? pc.green : quality >= 40 ? pc.yellow : pc.red;
+        onMeta?.(`\n  ${ctxBar}  ${pctColor(`${ctxPct}%`)}  ${pc.dim(`ctx: ${ctxTokens}/${ctxBudget.history}`)}  ${pc.dim(`compactions: ${compCount}`)}  ${qualityColor(`quality: ${quality}%`)}\n`);
+    }
+    renderCompaction(contextManager, onMeta) {
+        const compCount = contextManager.getCompactionCount();
+        if (compCount > this.lastCompactionShown) {
+            this.lastCompactionShown = compCount;
+            onMeta?.(pc.dim(`\n  ⟳ Context compacted (${compCount})\n`));
+        }
+    }
+}

package/dist/core/agent/hallucination-gate.js

@@ -0,0 +1,87 @@
+import { pc } from "../../ui/colors";
+import { t } from "../../i18n/index";
+import { MAX_HALLUCINATION_RETRIES } from "./constants";
+/**
+ * Вентиль проверки халлюцинаций финального текстового ответа.
+ *
+ * Объединяет весь граф вердиктов validate() (block/warn/retry) и их
+ * под-пути: exit-on-complete fast-exit, подавление повтора после отказа
+ * аудита (suppressRepetitionRetry), исчерпание повторов, добавление
+ * retry-контекста в сообщения.
+ *
+ * Возвращает структурированный вердикт; решение о `break`/`continue`/`return`
+ * принимает цикл. Вся мутация состояния живёт здесь — цикл остаётся тонким.
+ */
+export class HallucinationGate {
+    detector;
+    constructor(detector) {
+        this.detector = detector;
+    }
+    async evaluate(deps) {
+        const { state, textContent, logger } = deps;
+        // Обновляем базу сравнения ДО validate: confidence-чек смотрит на
+        // ПРЕДЫДУЩУЮ итерацию, иначе текст пересекался бы сам с собой.
+        this.detector.getConfidenceCheck().setPreviousResponse(state.lastModelText);
+        if (textContent)
+            state.lastModelText = textContent;
+        const result = await this.detector.validate(textContent);
+        if (result.status === "block") {
+            logger.warn(`Response blocked: ${result.reason}`);
+            return { action: "block", reason: result.reason || "" };
+        }
+        if (result.status === "warn") {
+            logger.warn(`Hallucination warning: ${result.reason}`);
+            this.displayWarnLine(result.reason, deps);
+            return { action: "warn" };
+        }
+        if (result.status === "retry") {
+            state.iterHallucinationRetry = true;
+            // Exit-on-complete fast-exit НЕ должен обходить финальный аудит: при
+            // активном плане модель может ответить "done" с невыполненными шагами
+            // (регрессия сертификации: модель ответила, не запустив свой скрипт).
+            // Короткое замыкание — только когда аудитить нечего.
+            if (deps.exitOnComplete && textContent?.trim() && !deps.hasFinalAudit) {
+                logger.debug("Exit-on-complete: stopping on first response");
+                // Сохраняем ДО break — lastText всё ещё текст предыдущей (туловой)
+                // итерации, и без этого итоговый ответ теряется (reported text: "").
+                state.lastText = textContent;
+                state.finalAnswerAccepted = true;
+                return { action: "exit" };
+            }
+            if (state.suppressRepetitionRetry && result.kind === "repetition") {
+                // Аудит отклонил предыдущий ответ и переспросил; его переформулировка
+                // выполненной задачи естественно "повторяющаяся" — это ожидаемо, а не
+                // деградация. Снижаем до предупреждения и пропускаем в acceptance path
+                // (сам аудит ограничен MAX_AUDIT_RETRIES).
+                state.suppressRepetitionRetry = false;
+                logger.warn(`Audit-triggered re-answer repetition — not counted as hallucination retry`);
+                this.displayWarnLine(result.reason, deps);
+                return { action: "accept" };
+            }
+            if (state.hallucinationRetries >= MAX_HALLUCINATION_RETRIES) {
+                logger.warn(`Hallucination retries exhausted (${MAX_HALLUCINATION_RETRIES}), returning error`);
+                return { action: "block", reason: t("hall.max_retries_exhausted") };
+            }
+            state.hallucinationRetries++;
+            logger.warn(`Hallucination retry (${state.hallucinationRetries}/${MAX_HALLUCINATION_RETRIES}): ${result.reason}`);
+            if (textContent) {
+                deps.contextManager.addMessage({ role: "assistant", content: textContent });
+            }
+            deps.contextManager.addMessage({
+                role: "user",
+                content: `<system-summary>[Retry context: ${result.reason}. Original task: "${deps.input}". You must either call a needed tool or provide a substantive response. Empty replies are not allowed.]</system-summary>`,
+            });
+            return { action: "retry" };
+        }
+        return { action: "accept" };
+    }
+    displayWarnLine(reason, deps) {
+        const warnLine = `${t("hall.uncertainty_prefix").trim()} ${reason ?? ""}`;
+        if (deps.onMeta) {
+            deps.onMeta(`\n${pc.yellow(warnLine)}\n`);
+        }
+        else if (deps.onChunk) {
+            deps.onChunk(`\n${warnLine}\n`);
+        }
+    }
+}

package/dist/core/agent/loop-state.js

@@ -0,0 +1,53 @@
+import { FORCED_COMPACTION_COOLDOWN } from "./constants";
+/** Фабрика начального состояния цикла. */
+export function createLoopState() {
+    return {
+        iteration: 0,
+        lastText: "",
+        lastModelText: "",
+        lastForcedCompactionIteration: -FORCED_COMPACTION_COOLDOWN,
+        hallucinationRetries: 0,
+        lastToolSignature: "",
+        consecutiveToolFailures: 0,
+        consecutiveToolSuccesses: 0,
+        repeatedToolCount: 0,
+        toolFailureCounts: new Map(),
+        memoryRuleRecorded: new Set(),
+        toolTargetCounts: new Map(),
+        cycleNudgedKeys: new Set(),
+        apiPromptTokens: 0,
+        apiCompletionTokens: 0,
+        apiCompletionChars: 0,
+        estimatedPromptTokensTotal: 0,
+        totalLlmDuration: 0,
+        cacheCachedTotal: 0,
+        cacheUncachedTotal: 0,
+        cacheWriteTotal: 0,
+        cacheSource: "none",
+        auditRetries: 0,
+        lastAuditSummary: "",
+        emptyResponseRetries: 0,
+        emptyResponseExhausted: false,
+        auditFailed: false,
+        finalAnswerAccepted: false,
+        suppressRepetitionRetry: false,
+        llmErrorRetries: 0,
+        iterHallucinationRetry: false,
+        iterAuditRejection: false,
+        iterRecoverableLlmError: false,
+        iterPlanCreated: false,
+        iterRepetitive: false,
+    };
+}
+/**
+ * Сброс per-итерационных сигналов reasoning policy. Вызывается в цикле
+ * ПОСЛЕ оценки политики (политика читает сигналы предыдущей итерации),
+ * перед тем как новые сигналы будут выставлены на текущем ходу.
+ */
+export function clearIterationSignals(state) {
+    state.iterHallucinationRetry = false;
+    state.iterAuditRejection = false;
+    state.iterRecoverableLlmError = false;
+    state.iterPlanCreated = false;
+    state.iterRepetitive = false;
+}

package/dist/core/agent/prefix-monitor.js

@@ -0,0 +1,101 @@
+// src/core/agent/prefix-monitor
+/**
+ * Клиентский монитор стабильности префикса промпта.
+ *
+ * Провайдеры кешируют только совпавший префикс промпта. Даже когда провайдер
+ * не сообщает cache-метрики (Ollama, экзотические прокси), агент может сам
+ * посчитать, насколько текущий промпт продолжает предыдущий, и — что важнее —
+ * ЧТО именно сломало префикс. Это не заменяет провайдерский `cached_tokens`,
+ * но работает всегда и не даёт спутать отсутствие данных с промахом кеша.
+ */
+/** Разделитель сегментов при склейке (провайдер склеивает поля сам). */
+const SEP = "\n";
+/**
+ * Маркеры «волатильного» содержимого. Если расхождение префикса попадает на
+ * дату/время/UUID/временный путь — это почти наверняка клиентская ошибка
+ * стабильности промпта, а не действие модели.
+ */
+const VOLATILE_RE = /(\d{4}-\d{2}-\d{2}|\d{2}:\d{2}:\d{2}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}|[A-Za-z]:\\|\\AppData\\|\\Temp\\|\/tmp\/)/;
+/** Детерминированная сериализация определений тулов для сравнения префикса. */
+export function serializeTools(tools) {
+    return tools
+        .map((t) => `${t.name}\u0001${t.description}\u0001${JSON.stringify(t.parameters)}`)
+        .join("\u0002");
+}
+/** Детерминированная сериализация истории сообщений для сравнения префикса. */
+export function serializeMessages(messages) {
+    return messages
+        .map((m) => `${m.role}\u0001${typeof m.content === "string" ? m.content : JSON.stringify(m.content)}`)
+        .join("\u0002");
+}
+/**
+ * Собирает снимок промпта из истории сообщений и определений тулов.
+ * Системные сообщения выделяются в отдельный сегмент — они стабильны и
+ * ломаются по другим причинам, чем история.
+ */
+export function buildPromptSnapshot(messages, tools) {
+    const system = [];
+    const rest = [];
+    for (const m of messages) {
+        if (m.role === "system")
+            system.push(m);
+        else
+            rest.push(m);
+    }
+    return {
+        system: serializeMessages(system),
+        tools: serializeTools(tools),
+        history: serializeMessages(rest),
+    };
+}
+/** Склейка сегментов в единую строку с запоминанием границ. */
+function frame(s) {
+    const full = s.system + SEP + s.tools + SEP + s.history;
+    const toolsStart = s.system.length + SEP.length;
+    const historyStart = toolsStart + s.tools.length + SEP.length;
+    return { full, toolsStart, historyStart };
+}
+/**
+ * Считает общий префикс текущего и предыдущего промпта и классифицирует
+ * причину расхождения. `countTokens` передаётся вызывающим, чтобы функция
+ * оставалась чистой и не тянула токенизатор в горячий путь.
+ */
+export function diffPrompt(prev, curr, countTokens) {
+    const c = frame(curr);
+    const currTokens = countTokens(c.full);
+    if (!prev) {
+        return {
+            prevTokens: 0,
+            currTokens,
+            commonPrefixTokens: 0,
+            stableRatio: 0,
+            cause: "unknown",
+        };
+    }
+    const p = frame(prev);
+    const prevTokens = countTokens(p.full);
+    // Общий префикс — посимвольно (нижняя граница токенного префикса).
+    const maxCp = Math.min(p.full.length, c.full.length);
+    let cp = 0;
+    while (cp < maxCp && p.full[cp] === c.full[cp])
+        cp++;
+    const commonPrefixTokens = countTokens(c.full.slice(0, cp));
+    const stableRatio = currTokens === 0 ? 0 : Math.min(1, commonPrefixTokens / currTokens);
+    // Префикс не сломан: идентично, дописано в хвост или усечено.
+    if (cp === maxCp) {
+        return { prevTokens, currTokens, commonPrefixTokens, stableRatio, cause: "none" };
+    }
+    let cause;
+    if (cp >= c.historyStart)
+        cause = "history";
+    else if (cp >= c.toolsStart)
+        cause = "tools";
+    else
+        cause = "system";
+    // Волатильное содержимое у точки расхождения перекрывает сегментную причину.
+    const window = (c.full.slice(Math.max(0, cp - 40), cp + 160) +
+        p.full.slice(Math.max(0, cp - 40), cp + 160));
+    if (VOLATILE_RE.test(window))
+        cause = "volatile";
+    return { prevTokens, currTokens, commonPrefixTokens, stableRatio, cause };
+}

package/dist/core/agent/reasoning-resolver.js

@@ -0,0 +1,56 @@
+import { evaluateReasoningPolicy } from "../../modules/reasoning/policy";
+/**
+ * Резолвер уровня reasoning на итерацию.
+ *
+ * Приоритет (сохранён из agent.ts):
+ * 1. Активный override от set_thinking (в окне overrideCooldown) — побеждает
+ *    и auto-режим, и фиксированный.
+ * 2. auto-режим + пройденный probe — политика (повышение на халлюцинации/
+ *    отказе аудита/ошибке LLM, понижение на рутине и повторах, затухание).
+ * 3. Фиксированный режим.
+ *
+ * ВАЖНО: сигналы политики (iter*) описывают события ПРЕДЫДУЩЕЙ итерации —
+ * они выставляются на retry-путях перед `continue`, поэтому политика должна
+ * оцениваться ДО их очистки (это делает вызывающий код через
+ * clearIterationSignals сразу после resolve).
+ */
+export class ReasoningEffortResolver {
+    resolve(deps) {
+        const { state, reasoningConfig, reasoningState } = deps;
+        let level;
+        const strategy = deps.reasoningStrategy;
+        let source = "policy";
+        const overrideCooldown = reasoningConfig?.overrideCooldown ?? 0;
+        const overrideAge = state.iteration - reasoningState.overrideIteration;
+        const overrideActive = overrideCooldown > 0 &&
+            reasoningState.overrideIteration >= 0 &&
+            overrideAge > 0 &&
+            overrideAge <= overrideCooldown;
+        if (reasoningState.manual) {
+            level = reasoningState.level;
+            source = "agent_override";
+        }
+        else if (overrideActive) {
+            level = reasoningState.level;
+            source = "agent_override";
+        }
+        else if (reasoningConfig && reasoningConfig.mode === "auto" && deps.probePassed) {
+            const policyResult = evaluateReasoningPolicy({
+                hallucinationRetry: state.iterHallucinationRetry,
+                auditRejection: state.iterAuditRejection,
+                recoverableLlmError: state.iterRecoverableLlmError,
+                planCreated: state.iterPlanCreated,
+                consecutiveSuccesses: state.consecutiveToolSuccesses,
+                isRepetitive: state.iterRepetitive,
+                baseline: reasoningConfig?.baseline ?? "medium",
+            }, deps.policyState);
+            level = policyResult.level;
+            source = "policy";
+        }
+        else if (reasoningConfig && reasoningConfig.mode !== "auto") {
+            level = reasoningConfig.mode;
+            source = "fixed";
+        }
+        return { level, strategy, source };
+    }
+}

package/dist/core/agent/token-tracker.js

@@ -0,0 +1,96 @@
+import { estimateTokens } from "../../llm/token-counter";
+/**
+ * Учёт токенов и стоимости за один запуск цикла.
+ *
+ * Отвечает за три вещи, которые в agent.ts были размазаны по циклу:
+ * 1) замену (НЕ аккумуляцию) running-сумм prompt/completion-токенов из
+ *    done-чанка стрима — `chat()` вызывается один раз за итерацию, поэтому
+ *    суммировать нельзя (иначе один реальный запрос посчитается дважды);
+ * 2) per-call лог usage + запись стоимости в CostTracker, с честным
+ *    разделением источника ("api" против локальной оценки, т.к. llama.cpp
+ *    часто опускает `usage` в стриминге);
+ * 3) финальные метрики результата: API-токены, если бэкенд их отдал,
+ *    иначе fallback-оценка (~4 символа на токен).
+ */
+export class TokenTracker {
+    costTracker;
+    getProviderName;
+    constructor(costTracker, getProviderName) {
+        this.costTracker = costTracker;
+        this.getProviderName = getProviderName;
+    }
+    /**
+     * Начало итерации: фиксирует baseline API-токенов и аккумулирует оценку
+     * prompt-токенов. Возвращает baseline для последующих вызовов.
+     */
+    beginIteration(state, estimatedPromptTokens) {
+        state.estimatedPromptTokensTotal += estimatedPromptTokens;
+        // Кеш-данные относятся к одной итерации; сбрасываем, чтобы отсутствие
+        // usage в следующем ходе не приписало старые цифры.
+        state.cacheUsage = undefined;
+        return {
+            promptBefore: state.apiPromptTokens,
+            completionBefore: state.apiCompletionTokens,
+        };
+    }
+    /**
+     * done-чанк стрима: ЗАМЕНЯЕТ running-суммы (promptBefore + usage), не
+     * аккумулирует — один логический запрос = один `done`.
+     */
+    recordApiUsage(state, baseline, usage) {
+        state.apiPromptTokens = baseline.promptBefore + usage.promptTokens;
+        state.apiCompletionTokens = baseline.completionBefore + usage.completionTokens;
+        state.cacheUsage = usage.cache;
+    }
+    /** Аккумулирует символы ответа — fallback-оценка completion-токенов. */
+    addCompletionChars(state, chars) {
+        state.apiCompletionChars += chars;
+    }
+    /**
+     * Per-call лог usage + запись стоимости. Источник "api", когда бэкенд
+     * отдал цифры; иначе локальная оценка (контекст для prompt, chars/4 для
+     * completion) — лог должен отличать реальные числа от эвристики.
+     */
+    logUsage(state, baseline, textContent, contextTokens, iteration, durationMs, slog) {
+        const usagePrompt = state.apiPromptTokens - baseline.promptBefore;
+        const usageCompletion = state.apiCompletionTokens - baseline.completionBefore;
+        const source = usagePrompt > 0 || usageCompletion > 0 ? "api" : "estimate";
+        const prompt = source === "api" ? usagePrompt : contextTokens;
+        const completion = source === "api" ? usageCompletion : estimateTokens(textContent);
+        // Накопление кеш-токенов за прогон (для AgentResult.cache).
+        if (state.cacheUsage) {
+            state.cacheCachedTotal += state.cacheUsage.cachedTokens;
+            state.cacheUncachedTotal += state.cacheUsage.uncachedTokens;
+            state.cacheWriteTotal += state.cacheUsage.cacheWriteTokens;
+            state.cacheSource = state.cacheUsage.source;
+        }
+        slog.logLlmUsage(iteration, {
+            promptTokens: prompt,
+            completionTokens: completion,
+            totalTokens: prompt + completion,
+            source,
+            durationMs,
+            prefix: state.prefixDelta,
+            cache: state.cacheUsage,
+        });
+        // Кеш учитываем только когда цифры пришли от API: оценка chars/4 о кеше
+        // ничего не знает и не должна менять тарификацию.
+        this.costTracker.record(prompt, completion, this.getProviderName(), source === "api" ? state.cacheUsage : undefined);
+    }
+    /**
+     * Финальные метрики результата. API-токены в приоритете; иначе — сумма
+     * оценок prompt по итерациям и символы completion (~4 символа/токен).
+     */
+    resolveFinal(state) {
+        if (state.apiPromptTokens > 0 || state.apiCompletionTokens > 0) {
+            return {
+                prompt: state.apiPromptTokens,
+                completion: state.apiCompletionTokens,
+                total: state.apiPromptTokens + state.apiCompletionTokens,
+            };
+        }
+        const prompt = Math.max(1, state.estimatedPromptTokensTotal);
+        const completion = Math.max(0, Math.ceil(state.apiCompletionChars / 4));
+        return { prompt, completion, total: prompt + completion };
+    }
+}