chatEngine.js

'use strict';

const EventEmitter = require('events');
const path = require('path');
const fs = require('fs');
const os = require('os');
const { pathToFileURL } = require('url');
const { parseToolCalls, repairToolCalls, stripToolCallText, isVisibleToolArtifact, looksLikeToolAttempt, suggestClosestToolName, extractPartialWriteFileFromToolJson, normalizeStreamingFilePath, resolveStreamingFileKey, _inferFilePath } = require('./tools/toolParser');
const { formatToolResultForInject, buildToolResultsUserMessage } = require('./tools/toolResultInjection');
const { canonicalizeToolParams } = require('./tools/canonicalizeToolParams');
const { visionServer } = require('./visionServer');
const { detectFamily, detectFamilyFromArch, detectParamSize } = require('./modelDetection');
const { getModelProfile, resolveSamplingProfile, resolveAgentDryRepeatPenalty } = require('./modelProfiles');
const {
  PLAN_MODE_ALLOWED_TOOLS,
  filterPlanModeToolCalls,
  isPlanFilePath,
  resolvePlanPhase,
  resolveAgentMode,
  getAgentSystemPrompt,
} = require('./agentModeResolver');
const streamTrace = require('./streamTrace');

/** Base max chars of each tool result injected into chat history.
 *  Actual cap is computed at runtime proportional to the model's context size
 *  (Rule 9: no hardcoded context numbers) so it works for any model from 2K to 128K context.
 */
const BASE_TOOL_RESULT_INJECT_CHARS = 32000;
// PL2: Per-tool-type multipliers (fraction of context-based cap).
// Browser tools need more because snapshots contain both element refs and page text.
// File/web tools need less because the model can re-read or re-fetch.
const TOOL_INJECT_MULTIPLIERS = {
  browser_snapshot: 1.5, browser_navigate: 1.5, browser_click: 1.5,
  browser_type: 1.5, browser_screenshot: 0.5,
  read_file: 0.5, fetch_webpage: 0.5, web_search: 0.25,
};

/** Whether file-content UI may stream during plan mode (plan files only until Build). */
function shouldStreamFileContentForAgent(options, filePath) {
  if (!options?.planMode || options.agentPhase === 'building') return true;
  return isPlanFilePath(filePath || '');
}

function _sfStripFenceMarkers(fenceBuf) {
  const trimmed = String(fenceBuf || '').trim();
  const open = trimmed.match(/^(`{3,})\s*(\w*)\s*\n?/);
  if (!open) return trimmed;
  let inner = trimmed.slice(open[0].length);
  const close = inner.match(/\n?(`{3,})\s*$/);
  if (close) inner = inner.slice(0, -close[0].length);
  return inner.trim();
}

/** Parse write_file / edit_file payload from a closed tool-json fence buffer. */
function _sfExtractFileWriteFromToolFence(fenceBuf) {
  try {
    const calls = parseToolCalls(fenceBuf);
    for (const c of calls) {
      if (RE_FILE_STREAM_TOOLS.test(c.tool)) {
        const p = c.params || {};
        const filePath = p.filePath || p.path;
        if (!filePath) continue;
        return {
          tool: c.tool,
          filePath: String(filePath),
          content: p.content ?? p.newText ?? '',
          oldText: p.oldText,
          isEdit: FILE_EDIT_OPS.has(c.tool),
        };
      }
    }
  } catch (_) { /* parseToolCalls may fail on partial buffers */ }
  const inner = _sfStripFenceMarkers(fenceBuf);
  if (!inner) return null;
  try {
    const parsed = JSON.parse(inner);
    const tool = parsed.tool || parsed.name;
    const params = parsed.params || parsed.parameters || parsed.arguments || parsed;
    if (tool && RE_FILE_STREAM_TOOLS.test(tool) && (params.filePath || params.path)) {
      return {
        tool,
        filePath: params.filePath || params.path,
        content: params.content ?? params.newText ?? '',
        oldText: params.oldText,
        isEdit: FILE_EDIT_OPS.has(tool),
      };
    }
  } catch (_) {}
  return null;
}

/** Bulk-replay file-content IPC when tool JSON fence closes without live char streaming. */
function _sfBulkReplayFileContentFromFence(fenceBuf, ctx) {
  const {
    onStreamEvent, options, streamedSet, normalizePath, allowNewStart, endCompleted, markActive,
  } = ctx;
  if (!fenceBuf || !onStreamEvent) return false;
  const info = _sfExtractFileWriteFromToolFence(fenceBuf);
  if (!info?.filePath || info.content == null) return false;
  if (!shouldStreamFileContentForAgent(options, info.filePath)) return false;
  const np = normalizePath(info.filePath);
  if (streamedSet.has(np)) {
    if (endCompleted.has(np)) {
      endCompleted.delete(np);
    } else {
      return false;
    }
  }
  if (!allowNewStart(info.filePath)) return false;

  const fileName = info.filePath.split(/[\\/]/).pop() || info.filePath;
  const ext = fileName.includes('.') ? fileName.split('.').pop().toLowerCase() : '';
  const content = String(info.content);
  onStreamEvent('file-content-start', {
    filePath: info.filePath,
    fileName,
    language: ext,
    fileKey: np,
    op: info.isEdit ? 'edit' : 'write',
    oldText: info.oldText != null ? String(info.oldText) : undefined,
  });
  streamedSet.add(np);
  markActive(info.filePath);
  const CHUNK = 4096;
  for (let i = 0; i < content.length; i += CHUNK) {
    onStreamEvent('file-content-token', content.slice(i, i + CHUNK));
  }
  onStreamEvent('file-content-end', { filePath: info.filePath, fileKey: np });
  endCompleted.add(np);
  markActive(null);
  return true;
}

/** Emit one atomic IPC event for a complete file write (native FC / batch prose path). */
function emitCompleteFileContentBlock(onStreamEvent, filePath, content, options, meta = {}) {
  if (!onStreamEvent || content == null) return;
  if (options && !shouldStreamFileContentForAgent(options, filePath)) return;
  const fp = filePath || '';
  const fn = fp.split(/[\\/]/).pop() || fp;
  const ext = fn.includes('.') ? fn.split('.').pop().toLowerCase() : '';
  const fileKey = resolveStreamingFileKey(fp, options?.projectPath);
  onStreamEvent('file-content-block-complete', {
    filePath: fp,
    fileName: fn,
    language: ext,
    fileKey,
    content: String(content),
    op: meta.op || 'write',
    oldText: meta.oldText != null ? String(meta.oldText) : undefined,
    newText: meta.newText != null ? String(meta.newText) : undefined,
  });
}

/**
 * Unescape a JSON string value fragment (no surrounding quotes).
 * Used to decode filePath from accumulated FC params buffer.
 */
function _jsonUnescape(s) {
  try { return JSON.parse('"' + s + '"'); } catch { return s; }
}

/**
 * Stream-decode a fragment of a JSON string value (no surrounding quotes).
 * Handles escape sequences that may be split across chunk boundaries.
 * Returns { out, escPending, ended }:
 *   out         — decoded content for this chunk
 *   escPending  — true if trailing \ needs next chunk to resolve
 *   ended       — true if unescaped " (end of JSON string) was found
 */
const {
  jsonStringChunkDecode: _jsonStringChunkDecode,
  createJsonStringStreamState: _createJsonStringStreamState,
  jsonStringStreamStep: _jsonStringStreamStep,
} = require('./tools/jsonStringChunkDecode');

function _decodeFenceContentEscape(ch) {
  switch (ch) {
    case 'n': return '\n';
    case 't': return '\t';
    case 'r': return '\r';
    case '"': return '"';
    case '\\': return '\\';
    case '/': return '/';
    case 'b': return '\b';
    case 'f': return '\f';
    default: return '\\' + ch;
  }
}

// Pre-compiled regex patterns for the streaming tool call filter.
// These are tested on line boundaries only — never on every character.
const RE_FENCE_HEADER = /^```\s*(\w*)\r?\n/;
/** Prose-only fence langs that may stream live to chat; code langs buffer until close → CodeBlock. */
const SF_PLAIN_FENCE_LANGS = new Set(['md', 'markdown']);

function _sfPlainFenceLang(fenceBuf) {
  const m = String(fenceBuf || '').match(/^```\s*(\w*)/i);
  return (m?.[1] || '').toLowerCase();
}

function _sfIsPlainMarkdownFence(fenceBuf) {
  return SF_PLAIN_FENCE_LANGS.has(_sfPlainFenceLang(fenceBuf));
}

/** Fence languages that must buffer until close — never stream tool JSON to prose. */
const SF_TOOL_FENCE_LANGS = new Set(['json', 'tool', 'tool_call', 'text', 'plaintext']);

function _sfIsToolFenceLang(lang) {
  const l = (lang || '').toLowerCase();
  if (!l) return false;
  if (SF_TOOL_FENCE_LANGS.has(l)) return true;
  if (l.includes('json') || l.includes('tool')) return true;
  if (/^j+s*o?n/.test(l)) return true;
  return false;
}

const SF_FENCE_PLAIN_MIN_BODY = 24;

/**
 * Whether a fence buffer at header detection should stream to prose chat.
 * Used by the stream filter and regression tests.
 * All non-tool markdown/code fences (html, css, js, md, …) stream live.
 */
function _sfFenceHeaderShouldStreamPlain(fenceBuf) {
  if (!RE_FENCE_HEADER.test(fenceBuf)) return false;
  const hm = fenceBuf.match(RE_FENCE_HEADER);
  const lang = (hm[1] || '').toLowerCase();
  const afterHeader = fenceBuf.slice(hm[0].length);
  if (_sfIsToolFenceLang(lang)) return false;
  if (afterHeader.length < SF_FENCE_PLAIN_MIN_BODY) return false;
  const looksLikeToolBody = _sfFenceBufferLooksLikeToolJson(afterHeader.slice(0, 8000))
    || _sfIsToolLikeJson(afterHeader.slice(0, 6000));
  if (looksLikeToolBody) return false;
  return true;
}

/** Agent/build mode where code fences should route to FileContentBlock instead of prose. */
function _sfIsAgentFileFenceMode(options) {
  if (!options) return false;
  if (options.askOnly || options.chatMode === 'ask') return false;
  if ((options.planMode || options.chatMode === 'plan') && options.agentPhase !== 'building') return false;
  return true;
}

/** Whether an in-progress fence should stream to FileContentBlock (agent mode, non-md, non-tool). */
function _sfShouldRouteAgentCodeFence(fenceBuf, options) {
  if (!_sfIsAgentFileFenceMode(options)) return false;
  if (!RE_FENCE_HEADER.test(fenceBuf)) return false;
  const hm = fenceBuf.match(RE_FENCE_HEADER);
  const lang = (hm[1] || '').toLowerCase();
  if (_sfIsToolFenceLang(lang)) return false;
  if (SF_PLAIN_FENCE_LANGS.has(lang)) return false;
  const afterHeader = fenceBuf.slice(hm[0].length);
  if (afterHeader.length < SF_FENCE_PLAIN_MIN_BODY) return false;
  const looksLikeToolBody = _sfFenceBufferLooksLikeToolJson(afterHeader.slice(0, 8000))
    || _sfIsToolLikeJson(afterHeader.slice(0, 6000));
  if (looksLikeToolBody) return false;
  return true;
}

function _sfExtractAgentFenceBody(fenceBuf) {
  const hm = String(fenceBuf || '').match(RE_FENCE_HEADER);
  if (!hm) return '';
  let body = fenceBuf.slice(hm[0].length);
  const closeMatch = body.match(/\n?`{3,}\s*$/);
  if (closeMatch) body = body.slice(0, -closeMatch[0].length);
  return body;
}

/** Infer project file path for a plain code fence in agent mode. */
function _sfInferAgentFenceFilePath(fenceBuf, contextText = '') {
  const hm = String(fenceBuf || '').match(RE_FENCE_HEADER);
  const lang = hm ? (hm[1] || '').toLowerCase() : '';
  const body = _sfExtractAgentFenceBody(fenceBuf);
  return _inferFilePath(`${contextText}\n${fenceBuf}`, body, lang);
}

/** Re-route think-buffer content that is really file/tool payload (not reasoning prose). */
function _sfRerouteThinkContentToFile(text, options, contextText = '') {
  if (!text || !_sfIsAgentFileFenceMode(options)) return null;
  const sample = String(text);
  if (_sfIsToolLikeJson(sample)) {
    const partial = extractPartialWriteFileFromToolJson(sample, { stripCompleteSuffix: true });
    if (partial?.filePath && partial.content != null) {
      return { filePath: partial.filePath, content: partial.content, op: partial.isEdit ? 'edit' : 'write', oldText: partial.oldText };
    }
  }
  const fenceRe = /```(\w*)\s*\n([\s\S]*)/;
  const fm = sample.match(fenceRe);
  if (fm) {
    const lang = (fm[1] || '').toLowerCase();
    if (!_sfIsToolFenceLang(lang) && !SF_PLAIN_FENCE_LANGS.has(lang)) {
      const body = fm[2].replace(/\n?`{3,}\s*$/, '');
      const filePath = _inferFilePath(`${contextText}\n${sample}`, body, lang);
      if (filePath) return { filePath, content: body, op: 'write' };
    }
  }
  if (/<!DOCTYPE|<html[\s>]/i.test(sample)) {
    const filePath = _inferFilePath(`${contextText}\n${sample}`, sample);
    if (filePath) return { filePath, content: sample, op: 'write' };
  }
  return null;
}

function _sfStripPlainCodeFencesFromProse(text) {
  if (!text) return text;
  return text.replace(/```(?!markdown\b|md\b)[\w-]*\s*\n[\s\S]*?```/gi, '').trim();
}

/** Keep fence markers; append closing ``` when generation ended mid-fence. */
function _sfPreparePlainFenceFlushPayload(fenceBuf) {
  if (!fenceBuf) return '';
  let payload = fenceBuf;
  const openMatch = payload.match(/^(`{3,})\s*(\w*)/);
  if (openMatch) {
    const tickLen = openMatch[1].length;
    const trimmed = payload.trimEnd();
    const closeRe = new RegExp('\\n`{' + tickLen + ',}\\s*$');
    if (!closeRe.test(trimmed)) {
      payload = trimmed + '\n' + '`'.repeat(tickLen);
    }
  }
  return payload;
}
// Tightened: only match tool-call schema, not arbitrary JSON with "tool" or "name" keys
const RE_TOOL_KEY = /"tool"\s*:\s*"[a-zA-Z0-9_]+"/;          // {"tool":"write_file"} or {"tool":"vscode_askQuestions"} — requires string value
const RE_NAME_KEY = /"name"\s*:\s*"[a-zA-Z0-9_]+(?:_[a-zA-Z0-9_]+)*"/; // {"name":"read_file"} or mixed-case
const RE_PARAMS_KEY = /"(?:params|parameters|arguments)"\s*:\s*\{/; // {"params":{ — strong tool-call signal
const RE_BARE_NAME_TOOL = /\{\s*"[a-z][a-z0-9_]+"\s*,\s*"params"\s*:/i; // {"find_files","params":{...}}

function _sfIsToolLikeJson(buf) {
  return RE_TOOL_KEY.test(buf)
    || (RE_NAME_KEY.test(buf) && RE_PARAMS_KEY.test(buf))
    || RE_BARE_NAME_TOOL.test(buf);
}

function _sfFenceBufferLooksLikeToolJson(buf) {
  if (!buf) return false;
  if (_sfIsToolLikeJson(buf)) return true;
  if (/^```(?:json|tool|tool_call|jjson)\s/i.test(buf.trimStart())) return true;
  if (/"tool"\s*:\s*"/.test(buf)) return true;
  return false;
}

/** Sanitize user message / digest text that embeds truncated editor file snippets. */
function _sanitizeFileSnippetText(text) {
  if (!text || typeof text !== 'string') return text;
  return text.replace(
    /\[Current file:\s*([^\]]+)\]\n[\s\S]*/,
    (_match, filePath) => `Current file: ${String(filePath).trim()} (snippet only — full content on disk; use read_file for complete file)`,
  );
}

/**
 * One-line hint after tool batches when todos exist but update_todo was not called.
 * @param {Array<{id:number,text?:string,status?:string}>} activeTodos
 * @param {string[]} executedTools
 * @param {number} consecutiveWithoutUpdate
 */
function buildTodoProgressHint(activeTodos, executedTools, consecutiveWithoutUpdate = 0) {
  if (!Array.isArray(activeTodos) || activeTodos.length === 0) return '';
  const tools = Array.isArray(executedTools) ? executedTools : [];
  if (tools.some((t) => t === 'update_todo' || t === 'write_todos')) return '';
  const open = activeTodos.filter((t) => t.status === 'pending' || t.status === 'in-progress');
  if (open.length === 0) return '';
  const pending = open.filter((t) => t.status === 'pending').length;
  const inProgress = open.filter((t) => t.status === 'in-progress').length;
  const counts = [
    pending > 0 ? `${pending} pending` : '',
    inProgress > 0 ? `${inProgress} in-progress` : '',
  ].filter(Boolean).join(', ');
  const idList = open.map((t) => `id ${t.id}: ${(t.text || '').slice(0, 60)}`).join('; ');
  let hint = `[System: Active todo list (${counts}). If you finished a step, call update_todo with that id and status "done" before starting the next tool. Items: ${idList}.]`;
  if (consecutiveWithoutUpdate >= 3) {
    hint += ' [Reminder: several tools ran without update_todo — mark finished steps done so the todo list stays accurate.]';
  }
  return `${hint}\n\n`;
}

function _sfExtractGeneratingToolName(buf) {
  const standard = buf.match(/"(?:tool|name)"\s*:\s*"([^"]+)"/);
  if (standard) return standard[1];
  const bare = buf.match(RE_BARE_NAME_TOOL);
  return bare ? bare[1] : 'unknown';
}
const RE_FILE_WRITE_TOOLS = /write_file|create_file|append_to_file/;
const RE_FILE_EDIT_TOOLS = /edit_file|replace_in_file/;
const RE_FILE_STREAM_TOOLS = /write_file|create_file|append_to_file|edit_file|replace_in_file/;
const RE_CONTENT_START = /"content"\s*:\s*"$/;
const RE_NEW_TEXT_START = /"newText"\s*:\s*"$/;
const RE_OLD_TEXT_CAPTURE = /"oldText"\s*:\s*"((?:\\.|[^"\\])*)"/;
const FILE_EDIT_OPS = new Set(['edit_file', 'replace_in_file']);
const RE_FILE_PATH = /"(?:filePath|path)"\s*:\s*"([^"]*)"/;
const RE_TOOL_OR_SYSTEM_INJECT = /^\[(?:Tool Results|System)\]/i;
const RE_CONTEXT_ROTATED = /\[System: (?:Context rotated|Session memory condensed)\]/i;
const LIST_DIRECTORY_INJECT_MAX_ITEMS = 50;
const DUPLICATE_TOOL_HINT_MESSAGE = '[System: You already called this exact tool with the same parameters twice in a row. Use the prior tool results or try a different approach.]';

function stableToolFingerprint(tool, params) {
  try {
    const keys = Object.keys(params ?? {}).sort();
    const sorted = {};
    for (const k of keys) sorted[k] = params[k];
    return `${tool}:${JSON.stringify(sorted)}`;
  } catch {
    return `${tool}:${String(params)}`;
  }
}

function trimListDirectoryInjectPayload(toolResult) {
  if (!toolResult?.success || !Array.isArray(toolResult.items)) return toolResult;
  if (toolResult.items.length <= LIST_DIRECTORY_INJECT_MAX_ITEMS) return toolResult;
  const omitted = toolResult.items.length - LIST_DIRECTORY_INJECT_MAX_ITEMS;
  return {
    ...toolResult,
    items: toolResult.items.slice(0, LIST_DIRECTORY_INJECT_MAX_ITEMS),
    listingNote: `NOT a complete listing — ${omitted} more entries omitted; use find_files or list a subdirectory.`,
  };
}

/** Web-facing tools — if these share a batch with workspace navigation tools, drop the latter (structural conflict rule). */
const WEB_TOOL_BATCH = new Set(['web_search', 'fetch_webpage', 'http_request']);
const WORKSPACE_NAV_TOOLS = new Set(['list_directory', 'get_project_structure']);

function filterWebWorkspaceToolConflict(calls) {
  if (!calls?.length) return calls;
  const hasWeb = calls.some((c) => WEB_TOOL_BATCH.has(c.tool));
  const hasWs = calls.some((c) => WORKSPACE_NAV_TOOLS.has(c.tool));
  if (!hasWeb || !hasWs) return calls;
  const dropped = calls.filter((c) => WORKSPACE_NAV_TOOLS.has(c.tool));
  const kept = calls.filter((c) => !WORKSPACE_NAV_TOOLS.has(c.tool));
  console.log(
    `[ChatEngine] Same-batch conflict: dropped workspace tool(s) ${dropped.map((d) => d.tool).join(', ')} because web tool(s) are present`,
  );
  return kept;
}

/** Hard floor for context window (aligned with llama.cpp 256-token alignment). */
const MIN_CONTEXT_FLOOR = 2048;
/** When requireMinContextForGpu is true, prefer at least this before accepting GPU offload. */
const MIN_CONTEXT_WHEN_GPU_REQUIRED = 4096;
/** VRAM reserved for activations, CUDA context, and allocator overhead during generation. */
const VRAM_GENERATION_OVERHEAD = 512 * 1024 * 1024;
/** Safety buffer subtracted from free VRAM before KV allocation. */
const VRAM_KV_BUFFER = 256 * 1024 * 1024;
const GiB = 1024 * 1024 * 1024;

/**
 * Runtime minimum usable context for auto mode — tiered by total VRAM (bytes), not GPU model.
 */
function computeAutoTargetContext({ vramTotal, vramFree, kvBytesPerToken, desiredMaxContext, trainMaxContext }) {
  let tierTarget = 4096;
  if (vramTotal >= 48 * GiB) tierTarget = 65536;
  else if (vramTotal >= 24 * GiB) tierTarget = 32768;
  else if (vramTotal >= 8 * GiB) tierTarget = 8192;

  let cap = tierTarget;
  if (trainMaxContext != null) cap = Math.min(cap, trainMaxContext);
  cap = Math.min(cap, desiredMaxContext);

  if (kvBytesPerToken > 0 && vramFree > 0) {
    const kvBudget = Math.max(0, vramFree - VRAM_GENERATION_OVERHEAD - VRAM_KV_BUFFER);
    const vramBounded = Math.floor(kvBudget / kvBytesPerToken / 2);
    if (vramBounded > 0) cap = Math.min(cap, vramBounded);
  }

  return Math.max(MIN_CONTEXT_FLOOR, cap);
}

/** Descending unique context targets for step-down when VRAM is tight. */
function buildContextTargetSteps(autoTarget, minContext) {
  const seen = new Set();
  const targets = [];
  for (const t of [autoTarget, MIN_CONTEXT_WHEN_GPU_REQUIRED, MIN_CONTEXT_FLOOR, minContext]) {
    const v = Math.floor(t);
    if (v > 0 && !seen.has(v)) {
      seen.add(v);
      targets.push(v);
    }
  }
  return targets.sort((a, b) => b - a);
}

/**
 * For one gpuLayers count: max context that fits in vramFree, or null.
 * @returns {{ gpuLayers: number, maxCtx: number, contextSize: number } | null}
 */
function computeLayerVramFit({
  vramFree,
  modelSizeBytes,
  totalLayers,
  gpuLayers,
  kvBytesPerToken,
  desiredMaxContext,
  minContext,
  vramOverheadBytes,
  vramBufferBytes,
  gpuConstrainedContext,
  weightsAlreadyLoaded = false,
}) {
  if (!vramFree || vramFree <= 0 || !totalLayers || !modelSizeBytes || !kvBytesPerToken) {
    return null;
  }
  const bytesPerLayer = modelSizeBytes / totalLayers;
  const gpuRatio = totalLayers > 0 ? gpuLayers / totalLayers : 0;
  const modelVram = weightsAlreadyLoaded ? 0 : gpuLayers * bytesPerLayer;
  // Post-load: overhead/buffer already consumed during load — do not double-subtract.
  const effectiveOverhead = weightsAlreadyLoaded ? 0 : vramOverheadBytes;
  const effectiveBuffer = weightsAlreadyLoaded ? 0 : vramBufferBytes;
  const availForKv = vramFree - modelVram - effectiveOverhead - effectiveBuffer;
  if (availForKv <= 0) return null;

  let maxCtx;
  if (gpuRatio > 0) {
    maxCtx = Math.floor(availForKv / (kvBytesPerToken * gpuRatio));
    if (gpuConstrainedContext && gpuRatio < 0.3) {
      const vramBoundedCtx = Math.floor(availForKv / kvBytesPerToken);
      if (vramBoundedCtx > 0) maxCtx = Math.min(maxCtx, vramBoundedCtx);
    }
  } else {
    maxCtx = Math.floor(availForKv / kvBytesPerToken);
  }

  const contextSize = Math.max(minContext, Math.min(maxCtx, desiredMaxContext));
  const kvOnGpu = kvBytesPerToken * contextSize * gpuRatio;
  if (modelVram + kvOnGpu + effectiveOverhead > vramFree) return null;

  return { gpuLayers, maxCtx, contextSize };
}

/**
 * Unified VRAM budget: pick (gpuLayers, contextSize) from runtime VRAM + GGUF metadata.
 * Post-load (fixedGpuLayers): context only. Pre-load: mode from vramBalance setting.
 *
 * @returns {{ gpuLayers: number, contextSize: number, budgetMeta?: object }}
 */
function computeUnifiedVramBudget({
  vramFree,
  vramTotal = 0,
  modelSizeBytes,
  totalLayers,
  kvBytesPerToken,
  desiredMaxContext,
  minContext = MIN_CONTEXT_FLOOR,
  vramOverheadBytes = VRAM_GENERATION_OVERHEAD,
  vramBufferBytes = VRAM_KV_BUFFER,
  gpuConstrainedContext = true,
  fixedGpuLayers = null,
  vramBalance = 'balanced',
  trainMaxContext = null,
}) {
  const fallback = {
    gpuLayers: fixedGpuLayers ?? 0,
    contextSize: Math.max(minContext, Math.min(desiredMaxContext, minContext)),
  };
  if (!vramFree || vramFree <= 0 || !totalLayers || totalLayers <= 0 || !modelSizeBytes) {
    return fallback;
  }
  if (!kvBytesPerToken || kvBytesPerToken <= 0) {
    return {
      gpuLayers: fixedGpuLayers ?? totalLayers,
      contextSize: desiredMaxContext,
    };
  }

  const fitParams = {
    vramFree,
    modelSizeBytes,
    totalLayers,
    kvBytesPerToken,
    desiredMaxContext,
    minContext,
    vramOverheadBytes,
    vramBufferBytes,
    gpuConstrainedContext,
  };

  // Post-load: layers locked, weights already in VRAM — maximize context for available memory.
  if (fixedGpuLayers != null) {
    const fit = computeLayerVramFit({ ...fitParams, gpuLayers: fixedGpuLayers, weightsAlreadyLoaded: true });
    if (fit) {
      return { gpuLayers: fixedGpuLayers, contextSize: fit.contextSize };
    }
    // fit returned null (measured free < remaining overhead) — re-run layer search without pre-load overhead.
    const postLoadRefit = computeUnifiedVramBudget({
      vramFree,
      vramTotal: vramTotal || vramFree,
      modelSizeBytes,
      totalLayers,
      kvBytesPerToken,
      desiredMaxContext,
      minContext,
      vramOverheadBytes,
      vramBufferBytes,
      gpuConstrainedContext,
      fixedGpuLayers: null,
      vramBalance,
      trainMaxContext,
    });
    return {
      gpuLayers: postLoadRefit.gpuLayers,
      contextSize: postLoadRefit.contextSize,
    };
  }

  const mode = vramBalance === 'speed' || vramBalance === 'context' ? vramBalance : 'balanced';
  const autoTarget = computeAutoTargetContext({
    vramTotal: vramTotal || vramFree,
    vramFree,
    kvBytesPerToken,
    desiredMaxContext,
    trainMaxContext,
  });
  const targetSteps = buildContextTargetSteps(autoTarget, minContext);

  // Speed: maximize gpuLayers; layer search uses minimum context budget so VRAM goes to weights.
  if (mode === 'speed') {
    let bestPartial = null;
    let bestCpuOnly = null;
    for (let gpuLayers = totalLayers; gpuLayers >= 0; gpuLayers--) {
      const fit = computeLayerVramFit({
        ...fitParams,
        gpuLayers,
        desiredMaxContext: minContext,
      });
      if (!fit) continue;
      if (gpuLayers > 0) {
        const score = gpuLayers * 1_000_000 + fit.contextSize;
        if (!bestPartial || score > bestPartial.score) {
          bestPartial = { ...fit, score };
        }
      } else {
        const score = fit.contextSize;
        if (!bestCpuOnly || score > bestCpuOnly.score) {
          bestCpuOnly = { ...fit, score };
        }
      }
    }
    if (bestPartial) {
      const finalFit = computeLayerVramFit({
        ...fitParams,
        gpuLayers: bestPartial.gpuLayers,
        desiredMaxContext,
      });
      return {
        gpuLayers: bestPartial.gpuLayers,
        contextSize: finalFit?.contextSize ?? bestPartial.contextSize,
        budgetMeta: { mode, autoTarget, targetUsed: null },
      };
    }
    if (bestCpuOnly) {
      return {
        gpuLayers: 0,
        contextSize: bestCpuOnly.contextSize,
        budgetMeta: { mode, autoTarget, targetUsed: null },
      };
    }
    return { ...fallback, budgetMeta: { mode, autoTarget, targetUsed: null } };
  }

  // Context: maximize contextSize among fits meeting target; tie-break higher gpuLayers.
  if (mode === 'context') {
    for (const target of targetSteps) {
      let best = null;
      for (let gpuLayers = 1; gpuLayers <= totalLayers; gpuLayers++) {
        const fit = computeLayerVramFit({ ...fitParams, gpuLayers });
        if (!fit || fit.maxCtx < target) continue;
        if (!best || fit.contextSize > best.contextSize
          || (fit.contextSize === best.contextSize && fit.gpuLayers > best.gpuLayers)) {
          best = { ...fit, targetUsed: target };
        }
      }
      if (best) {
        return {
          gpuLayers: best.gpuLayers,
          contextSize: best.contextSize,
          budgetMeta: { mode, autoTarget, targetUsed: best.targetUsed },
        };
      }
    }
    const cpuFit = computeLayerVramFit({ ...fitParams, gpuLayers: 0 });
    if (cpuFit) {
      return {
        gpuLayers: 0,
        contextSize: cpuFit.contextSize,
        budgetMeta: { mode, autoTarget, targetUsed: MIN_CONTEXT_FLOOR, cpuFallback: true },
      };
    }
    return { ...fallback, budgetMeta: { mode, autoTarget, targetUsed: null } };
  }

  // Balanced (default): highest gpuLayers where maxCtx >= target; step down target if needed.
  for (const target of targetSteps) {
    for (let gpuLayers = totalLayers; gpuLayers >= 1; gpuLayers--) {
      const fit = computeLayerVramFit({ ...fitParams, gpuLayers });
      if (!fit || fit.maxCtx < target) continue;
      const contextSize = Math.max(minContext, Math.min(fit.maxCtx, desiredMaxContext));
      return {
        gpuLayers,
        contextSize,
        budgetMeta: {
          mode,
          autoTarget,
          targetUsed: target,
          targetSteppedDown: target < autoTarget,
        },
      };
    }
  }

  const cpuFit = computeLayerVramFit({ ...fitParams, gpuLayers: 0 });
  if (cpuFit) {
    return {
      gpuLayers: 0,
      contextSize: cpuFit.contextSize,
      budgetMeta: { mode, autoTarget, targetUsed: null, cpuFallback: true },
    };
  }
  return { ...fallback, budgetMeta: { mode, autoTarget, targetUsed: null } };
}

/** Approximate chars per token for English tool prompts. */
const TOOL_PROMPT_CHARS_PER_TOKEN = 3.5;

/**
 * Size tool catalog to remaining prompt budget (Bug 5).
 * Appends compact category parts until budget exhausted; falls back to full if it fits.
 */
/** Tier-0 tool parts: header + Browser + Core Files + Terminal — never dropped in Agent mode. */
const AGENT_TOOL_TIER0_PART_COUNT = 4;
/** Legacy default — use resolveAgentMinToolPromptChars(tier) for agent mode. */
const AGENT_MIN_TOOL_PROMPT_CHARS = 10000;

/** Minimum tool-catalog chars reserved in agent prefill, scaled by model size tier. */
function resolveAgentMinToolPromptChars(sizeTier) {
  switch (sizeTier) {
    case 'tiny': return 0;
    case 'small': return 2048;
    case 'medium': return 4096;
    case 'large': return 8192;
    case 'xlarge': return AGENT_MIN_TOOL_PROMPT_CHARS;
    default: return AGENT_MIN_TOOL_PROMPT_CHARS;
  }
}

/** Small models use compact tool parts only — skip injecting the full prose catalog. */
function preferCompactToolCatalogForTier(sizeTier) {
  return sizeTier === 'tiny' || sizeTier === 'small';
}

/** Prefer compact tool catalog when prefill is crowded or full catalog won't fit. */
function shouldPreferCompactToolCatalog({
  contextTokens,
  basePromptChars,
  historyChars = 0,
  userMessageChars = 0,
  fullToolPromptChars = 0,
  sizeTier = 'large',
}) {
  if (preferCompactToolCatalogForTier(sizeTier)) return true;
  const consumed = basePromptChars + historyChars + userMessageChars;
  const prefillPressure = contextTokens > 0 ? consumed / contextTokens : 0;
  const reservedTokens = Math.floor(contextTokens * 0.22) + 512;
  const remainingChars = Math.max(0, (contextTokens - reservedTokens) * TOOL_PROMPT_CHARS_PER_TOKEN - consumed);
  return prefillPressure > 0.35 || (fullToolPromptChars > 0 && fullToolPromptChars > remainingChars);
}

function buildBudgetProportionalToolPrompt({
  contextTokens,
  basePromptChars,
  historyChars = 0,
  userMessageChars = 0,
  toolPrompt = '',
  compactToolParts = null,
  compactToolPrompt = '',
  minGenerationReserve = 512,
  maxToolBudgetPct = 0.35,
  maxToolBudgetTokens = 4096,
  agentMode = false,
  agentMinToolPromptChars = AGENT_MIN_TOOL_PROMPT_CHARS,
  preferCompactCatalog = false,
}) {
  const tier0PartCount = (Array.isArray(compactToolParts) && compactToolParts._tier0PartCount) || AGENT_TOOL_TIER0_PART_COUNT;

  const fullToolTokens = Math.ceil((toolPrompt?.length || 0) / TOOL_PROMPT_CHARS_PER_TOKEN);
  const minToolChars = agentMode ? Math.max(0, agentMinToolPromptChars) : 0;
  const reservedToolTokens = agentMode
    ? Math.min(fullToolTokens, Math.max(Math.floor(minToolChars / TOOL_PROMPT_CHARS_PER_TOKEN), Math.floor(contextTokens * 0.22)))
    : 0;

  const consumedTokens = Math.ceil((basePromptChars + historyChars + userMessageChars) / TOOL_PROMPT_CHARS_PER_TOKEN);
  const promptBudgetTokens = Math.max(256, contextTokens - minGenerationReserve - consumedTokens - reservedToolTokens);
  const maxToolTokens = agentMode
    ? Math.max(reservedToolTokens, Math.min(Math.floor(promptBudgetTokens * maxToolBudgetPct), maxToolBudgetTokens))
    : Math.min(Math.floor(promptBudgetTokens * maxToolBudgetPct), maxToolBudgetTokens);
  let maxToolChars = Math.floor(maxToolTokens * TOOL_PROMPT_CHARS_PER_TOKEN);

  const parts = Array.isArray(compactToolParts) && compactToolParts.length > 0
    ? compactToolParts
    : (compactToolPrompt ? [compactToolPrompt] : []);

  if (!preferCompactCatalog && toolPrompt && fullToolTokens <= maxToolTokens) {
    return { prompt: toolPrompt, mode: 'full', budgetTokens: maxToolTokens, usedTokens: fullToolTokens, tier0Ok: true };
  }

  if (parts.length > 0 && preferCompactCatalog) {
    const built = parts.join('');
    const tier0Ok = !agentMode || (built.includes('browser_navigate') && built.includes('browser_snapshot'));
    return {
      prompt: built,
      mode: 'compact-all',
      budgetTokens: maxToolTokens,
      partsUsed: parts.length,
      usedTokens: Math.ceil(built.length / TOOL_PROMPT_CHARS_PER_TOKEN),
      tier0Ok,
      reservedToolTokens,
    };
  }

  if (parts.length === 0) {
    const trimmed = toolPrompt && toolPrompt.length > maxToolChars
      ? toolPrompt.slice(0, maxToolChars) + '\n…and more tools available\n'
      : (toolPrompt || '');
    return { prompt: trimmed, mode: 'trimmed-full', budgetTokens: maxToolTokens, usedTokens: Math.ceil(trimmed.length / TOOL_PROMPT_CHARS_PER_TOKEN), tier0Ok: !agentMode };
  }

  let built = '';
  let partsUsed = 0;
  const headerPart = parts[0] || '';
  const tier0End = agentMode ? Math.min(tier0PartCount, parts.length) : 0;

  if (agentMode && tier0End > 0) {
    for (let i = 0; i < tier0End; i++) {
      built += parts[i];
      partsUsed++;
    }
    maxToolChars = Math.max(maxToolChars, built.length);
  }

  for (let i = tier0End; i < parts.length; i++) {
    const part = parts[i];
    const next = built + part;
    if (next.length > maxToolChars && built.length > 0) break;
    built = next;
    partsUsed++;
  }

  if (!built && headerPart) {
    built = headerPart.length > maxToolChars ? headerPart.slice(0, maxToolChars) : headerPart;
    partsUsed = 1;
  } else if (headerPart && !built.startsWith(headerPart)) {
    const body = built.slice(headerPart.length);
    const maxBody = Math.max(0, maxToolChars - headerPart.length);
    built = headerPart + (maxBody > 0 ? body.slice(0, maxBody) : '');
    partsUsed = Math.max(partsUsed, 1);
  }
  if (partsUsed < parts.length) {
    built += '\n…and more tools available\n';
  }

  const tier0Ok = !agentMode || (built.includes('browser_navigate') && built.includes('browser_snapshot'));
  return {
    prompt: built,
    mode: agentMode && tier0End > 0 ? 'agent-tier0' : 'budget-parts',
    budgetTokens: maxToolTokens,
    partsUsed,
    usedTokens: Math.ceil(built.length / TOOL_PROMPT_CHARS_PER_TOKEN),
    tier0Ok,
    reservedToolTokens,
  };
}

/**
 * Normalize settings / IPC payload for model load. Matches settingsManager defaults when fields are missing.
 * @param {object} raw
 * @returns {{ gpuPreference: 'auto'|'cpu', gpuLayers: number, contextSize: number, requireMinContextForGpu: boolean }}
 */
/**
 * Absolute floor for the computed hardware context cap when GGUF metadata is
 * missing (so we cannot compute a KV-derived cap). Equal to the llama.cpp-aligned
 * minimum — used only as a last resort; the normal path computes from architecture.
 */
const CONTEXT_MAX_FALLBACK_NO_GGUF_FLOOR = 2048;

/**
 * Estimate KV-cache bytes per token from GGUF architecture metadata.
 * Transformer-standard, architecture-agnostic:
 *   KV per token = n_layer * n_head_kv * (key_length + value_length) * bytes_per_element
 * Assumes fp16 KV cache (2 bytes/element), the llama.cpp default.
 *
 * GGUF metadata shape (llama.cpp convention):
 *   architectureMetadata.block_count        → n_layer
 *   architectureMetadata.attention.head_count_kv   → n_head_kv
 *   architectureMetadata.attention.head_count      → n_head (fallback)
 *   architectureMetadata.attention.key_length      → head_dim_k
 *   architectureMetadata.attention.value_length    → head_dim_v
 *   architectureMetadata.embedding_length          → embedding dim (fallback)
 */
function estimateKvBytesPerToken(am, kvCacheType) {
  if (!am) return null;
  const nLayer = am.block_count;
  if (!nLayer) return null;
  const att = am.attention || {};
  const nHeadKv = att.head_count_kv || att.head_count;
  if (!nHeadKv) return null;
  let keyLen = att.key_length;
  let valLen = att.value_length;
  // Fallback: derive head_dim from embedding_length / head_count if per-head lengths missing
  if ((!keyLen || !valLen) && am.embedding_length && att.head_count) {
    const headDim = am.embedding_length / att.head_count;
    if (Number.isFinite(headDim) && headDim > 0) {
      if (!keyLen) keyLen = headDim;
      if (!valLen) valLen = headDim;
    }
  }
  if (!keyLen || !valLen) return null;
  // Bytes per element depends on KV cache quantization type:
  //   f16  = 2 bytes/element (no compression)
  //   q8_0 = 1 byte/element  (2x compression)
  //   q4_0 = 0.5 bytes/element (4x compression)
  const bytesPerElement = kvCacheType === 'q3_0' ? 0.375
    : kvCacheType === 'q4_0' ? 0.5
    : kvCacheType === 'q4_1' ? 0.5625
    : kvCacheType === 'q5_0' ? 0.625
    : kvCacheType === 'q5_1' ? 0.6875
    : kvCacheType === 'q8_0' ? 1
    : 2; // f16 or default
  return nLayer * nHeadKv * (keyLen + valLen) * bytesPerElement;
}

function buildEngineLoadSettings(raw = {}) {
  const gpuPreference = raw.gpuPreference === 'cpu' ? 'cpu' : 'auto';
  const gpuLayers = typeof raw.gpuLayers === 'number' ? raw.gpuLayers : -1;
  const ctx = Number(raw.contextSize);
  // 0 = auto — use model train cap (and VRAM) as upper bound, not a fixed 16k default
  const contextSize = !Number.isFinite(ctx) || ctx < 0 ? 0 : Math.floor(ctx);
  return {
    gpuPreference,
    gpuLayers,
    contextSize,
    requireMinContextForGpu: !!raw.requireMinContextForGpu,
    gpuConstrainedContext: raw.gpuConstrainedContext !== false, // default true
    vramBalance: raw.vramBalance === 'speed' || raw.vramBalance === 'context' ? raw.vramBalance : 'balanced',
    kvCacheType: raw.kvCacheType || 'q8_0',
    enableThinking: raw.enableThinking !== false, // default true
    // 'C' = ThinkingOpenJinja (prefix injection), 'B' = raw Jinja (no prefix), 'auto' = node-llama-cpp auto, 'off' = Jinja enable_thinking=false
    thinkingMode: raw.thinkingMode || 'C',
  };
}

/**
 * Mode C (independent harness): open the thought segment at generation start via
 * noPrefixTrigger. Used only for custom Jinja + enable_thinking wrappers — not for
 * chatWrapper=auto (QwenChatWrapper, Phi instruct, etc.).
 */
function createThinkingOpenJinjaWrapper(JinjaTemplateChatWrapper, LlamaText) {
  return class ThinkingOpenJinjaChatWrapper extends JinjaTemplateChatWrapper {
    generateContextState({ chatHistory, availableFunctions, documentFunctionParams }) {
      const state = super.generateContextState({ chatHistory, availableFunctions, documentFunctionParams });
      if (this.additionalRenderParameters?.enable_thinking !== true) return state;
      const thoughtSeg = this.settings?.segments?.thought;
      if (thoughtSeg?.prefix == null) return state;
      return {
        ...state,
        noPrefixTrigger: {
          type: 'segment',
          segmentType: 'thought',
          inject: LlamaText(thoughtSeg.prefix),
        },
      };
    }
  };
}

// Default session system entry — agent mode; per-request chat() uses resolveAgentMode().baseSystemPrompt
const SYSTEM_PROMPT = getAgentSystemPrompt();

class ChatEngine extends EventEmitter {
  constructor() {
    super();
    console.log('[ChatEngine] constructor START');
    this.isReady = false;
    this.isLoading = false;
    /** @type {'idle'|'loading'|'ready'|'disposing'} */
    this._loadState = 'idle';
    this._loadPromise = null;
    this.modelInfo = null;
    this.currentModelPath = null;
    this.gpuPreference = 'auto';
    this._projectPath = null;

    this._llama = null;
    this._model = null;
    this._context = null;
    this._sequence = null;
    this._chat = null;
    this._baseCtxOpts = null; // saved from loadModel() for summarizer VRAM reclaim
    this._chatHistory = [];
    this._lastEvaluation = null;
    this._abortController = null;
    this._cancelRequested = false;
    this._pendingUserMessage = null; // injected by user interrupt during tool loop
    this._templateSupportsThinking = false;
    this._thinkingCapable = false;
    this._recentlyWrittenFiles = new Map(); // filePath → content written in current chat() call
    this._fileContentStreamActivePath = null;
    this._sessionId = 0; // increments on resetSession to detect stale tool results
    this._activeChatPromise = null; // serializes concurrent chat() calls on singleton engine
    this._consecutiveToolsWithoutTodoUpdate = 0;
    console.log('[ChatEngine] constructor DONE');
  }

  /**
   * Wait until the in-flight chat() finishes (e.g. after cancelGeneration).
   * Swallows errors from cancelled turns.
   */
  async waitForIdle({ timeoutMs = 5000 } = {}) {
    if (!this._activeChatPromise) return;
    console.log('[ChatEngine] waitForIdle: awaiting active chat');
    streamTrace.trace('stream', 'waitForIdle-start', { timeoutMs });
    let timer;
    const timeout = new Promise((_, reject) => {
      timer = setTimeout(() => reject(new Error('waitForIdle timeout')), timeoutMs);
    });
    try {
      await Promise.race([this._activeChatPromise, timeout]);
      streamTrace.trace('stream', 'waitForIdle-done', { timeoutMs });
    } catch (err) {
      if (err?.message === 'waitForIdle timeout') {
        console.warn(`[ChatEngine] waitForIdle: timed out after ${timeoutMs}ms`);
        streamTrace.trace('stream', 'waitForIdle-timeout', { timeoutMs });
      }
    } finally {
      if (timer) clearTimeout(timer);
    }
  }

  async waitForReady() {
    if (this._loadPromise) {
      try { await this._loadPromise; } catch (_) { /* load failed */ }
    }
    return this.isReady && this._loadState === 'ready';
  }

  /**
   * @param {string} modelPath
   * @param {object} [rawLoadSettings] — from settingsManager.get() (gpuPreference, gpuLayers, contextSize, requireMinContextForGpu)
   */
  async initialize(modelPath, rawLoadSettings) {
    // If a load is already in progress, wait for it to finish, then proceed with this new request.
    // This prevents "Already loading a model" errors when the user switches models quickly.
    if (this._loadPromise) {
      console.log('[ChatEngine] Model load already in progress — queuing new request');
      try { await this._loadPromise; } catch (_) { /* previous load failed — proceed */ }
    }

    // Build a new promise for this load so subsequent requests can await it
    this._loadPromise = this._doInitialize(modelPath, rawLoadSettings);
    try {
      return await this._loadPromise;
    } finally {
      this._loadPromise = null;
    }
  }

  async _doInitialize(modelPath, rawLoadSettings, { isRollback = false } = {}) {
    const rollback = !isRollback && this.modelInfo?.path && this._loadState === 'ready'
      ? { path: this.modelInfo.path, settings: rawLoadSettings }
      : null;

    this._loadState = 'loading';
    this.isLoading = true;
    this.isReady = false;
    this.emit('status', { state: 'loading', message: 'Loading model...' });

    try {
      const llamaCppPath = this._getNodeLlamaCppPath();
      const { getLlama, LlamaChat, readGgufFileInfo, JinjaTemplateChatWrapper, LlamaText } = await import(pathToFileURL(llamaCppPath).href);
      const ThinkingOpenJinjaChatWrapper = createThinkingOpenJinjaWrapper(JinjaTemplateChatWrapper, LlamaText);
      // Save class refs so setWrapperMode can recreate wrappers without a model reload
      this._LlamaChat = LlamaChat;
      this._JinjaTemplateChatWrapper = JinjaTemplateChatWrapper;
      this._ThinkingOpenJinjaChatWrapper = ThinkingOpenJinjaChatWrapper;

      const s = buildEngineLoadSettings(rawLoadSettings || {});
      this.gpuPreference = s.gpuPreference;

      if (this._model) {
        this._loadState = 'disposing';
        await this._dispose();
        this._loadState = 'loading';
      }

      let trainMaxContext = null;
      let totalLayersFromGguf = null;
      let ggufArchMeta = null;
      let ggufArchString = null; // metadata.general.architecture (e.g. "chatglm", "qwen35", "gemma3")
      let ggufChatTemplate = null; // tokenizer.chat_template — Jinja template string from GGUF metadata
      try {
        const gguf = await readGgufFileInfo(modelPath, { readTensorInfo: false, logWarnings: false });
        const am = gguf.architectureMetadata;
        ggufArchMeta = am || null;
        if (gguf.metadata?.general?.architecture) ggufArchString = gguf.metadata.general.architecture;
        if (am && typeof am.context_length === 'number') trainMaxContext = am.context_length;
        if (am && typeof am.block_count === 'number') totalLayersFromGguf = am.block_count;
        // Tier 1: Extract chat template from GGUF metadata for auto-detection.
        // tokenizer.chat_template is a Jinja2 string embedded in the GGUF file.
        // It's the authoritative source for what the model's chat format supports.
        // Models with thinking capability include `enable_thinking` as a Jinja variable.
        if (gguf.metadata?.tokenizer?.chat_template) {
          ggufChatTemplate = gguf.metadata.tokenizer.chat_template;
        }
      } catch (e) {
        console.warn(`[ChatEngine] readGgufFileInfo: ${e.message}`);
      }

      // Initialize llama runtime early so we can query VRAM state before context sizing.
      const gpuOpt = s.gpuPreference === 'cpu' ? false : 'auto';
      this._llama = await this._createLlamaRuntime(getLlama, gpuOpt);

      const modelStats = fs.statSync(modelPath);

      // ─── Hardware-aware context ceiling computation ───
      // Compute the maximum context window that the user's hardware can realistically support,
      // derived from GGUF architecture + available memory. No hardcoded ceilings.
      const kvBytesPerToken = estimateKvBytesPerToken(ggufArchMeta, s.kvCacheType);
      let hardwareCap = null;
      let kvSourceMem = 'none';
      let vramTotal = 0;
      let vramFree = 0;
      // Diagnostic: log raw GGUF architecture metadata for KV estimate verification
      if (ggufArchMeta) {
        const att = ggufArchMeta.attention || {};
        console.log(`[ChatEngine] GGUF arch metadata: block_count=${ggufArchMeta.block_count}, head_count_kv=${att.head_count_kv}, head_count=${att.head_count}, key_length=${att.key_length}, value_length=${att.value_length}, embedding_length=${ggufArchMeta.embedding_length}, kvCacheType=${s.kvCacheType}, kvBytesPerToken=${kvBytesPerToken}`);
      }
      if (kvBytesPerToken) {
        // Compute hwCap from both VRAM and RAM, pick whichever gives larger context.
        // Previously we preferred VRAM whenever possible, but for small models that
        // nearly fill VRAM, this gave tiny contexts (e.g. 12K) when RAM would give 32K+.
        let vramHwCap = null;
        let ramHwCap = null;
        if (s.gpuPreference !== 'cpu') {
          try {
            const vramState = await this._llama.getVramState();
            vramTotal = vramState?.total || 0;
            vramFree = vramState?.free || 0;
          } catch (e) { console.warn('[ChatEngine] VRAM state query failed:', e.message); }
        }
        // VRAM path: free VRAM minus model weights, half reserved for KV
        if (vramFree > modelStats.size) {
          const vramAvail = vramFree - modelStats.size;
          const vramKvBudget = vramAvail / 2;
          vramHwCap = Math.max(MIN_CONTEXT_FLOOR, Math.floor(vramKvBudget / kvBytesPerToken));
        }
        // RAM path. useMmap=true (line 445) means model weights are
        // memory-mapped and shared with the OS page cache, NOT consuming
        // anonymous RAM upfront. Deriving from os.freemem() and subtracting
        // modelStats.size double-counts on every OS with mmap and collapses
        // to MIN_CONTEXT_FLOOR when free memory is tight at load time.
        // Use os.totalmem() (deterministic upper bound, independent of
        // transient memory state) minus the model file size minus a fixed
        // runtime overhead for activations, the JS/Electron heap, sub-agent
        // context, and OS slack. A precise computation would need gpuLayers,
        // which is computed AFTER hardwareCap (chicken-and-egg) — fixed
        // constant is the right tradeoff here.
        const RAM_RUNTIME_OVERHEAD = 1.5 * 1024 * 1024 * 1024;
        const ramAvail = Math.max(0, os.totalmem() - modelStats.size - RAM_RUNTIME_OVERHEAD);
        const ramKvBudget = ramAvail / 2;
        ramHwCap = Math.max(MIN_CONTEXT_FLOOR, Math.floor(ramKvBudget / kvBytesPerToken));

        // Pick whichever source gives the larger context
        if (vramHwCap != null && vramHwCap >= ramHwCap) {
          hardwareCap = vramHwCap;
          kvSourceMem = 'vram';
        } else {
          hardwareCap = ramHwCap;
          kvSourceMem = 'ram';
        }
        console.log(`[ChatEngine] Memory diagnostic: vramTotal=${(vramTotal/1e9).toFixed(2)}GB, vramFree=${(vramFree/1e9).toFixed(2)}GB, freeRam=${(os.freemem()/1e9).toFixed(2)}GB, modelSize=${(modelStats.size/1e9).toFixed(2)}GB, vramHwCap=${vramHwCap}, ramHwCap=${ramHwCap}, source=${kvSourceMem}, hwCap=${hardwareCap}`);
      }

      const testMaxCtx = parseInt(process.env.TEST_MAX_CONTEXT, 10) || 0;
      let desiredMax;
      if (testMaxCtx > 0) {
        desiredMax = testMaxCtx;
      } else if (s.contextSize <= 0) {
        // P4: Auto sizing uses only hardware cap and train cap (no hardcoded ceiling).
        // Per RULES.md Rule 9: never hardcode context numbers — compute from actual resources.
        // The hardware cap already accounts for VRAM/RAM headroom, so it self-limits to safe sizes.
        if (hardwareCap != null && trainMaxContext != null) {
          desiredMax = Math.min(hardwareCap, trainMaxContext);
        } else if (hardwareCap != null) {
          desiredMax = hardwareCap;
        } else if (trainMaxContext != null) {
          desiredMax = trainMaxContext;
        } else {
          desiredMax = CONTEXT_MAX_FALLBACK_NO_GGUF_FLOOR;
        }
      } else {
        desiredMax = s.contextSize;
        if (trainMaxContext != null) desiredMax = Math.min(desiredMax, trainMaxContext);
        desiredMax = Math.max(MIN_CONTEXT_FLOOR, desiredMax);
      }

      const minBase = s.requireMinContextForGpu ? MIN_CONTEXT_WHEN_GPU_REQUIRED : MIN_CONTEXT_FLOOR;
      let contextMin = Math.min(minBase, desiredMax);

      // When model weights exceed VRAM, RAM hwCap can inflate desiredMax to 100K+ and the
      // unified budget picks gpuLayers=0 with a mega KV cache. Cap desiredMax from VRAM so
      // partial GPU offload remains viable on 4GB GPUs.
      if (s.gpuPreference !== 'cpu' && kvBytesPerToken > 0 && modelStats.size > vramFree * 0.85) {
        const vramKvBudget = vramFree - VRAM_GENERATION_OVERHEAD - VRAM_KV_BUFFER;
        const vramCtxCap = Math.max(MIN_CONTEXT_FLOOR, Math.floor(vramKvBudget / kvBytesPerToken));
        if (desiredMax > vramCtxCap) {
          console.log(`[ChatEngine] Model (${(modelStats.size / 1e9).toFixed(2)}GB) exceeds VRAM (${(vramFree / 1e9).toFixed(2)}GB free) — capping desiredMax ${desiredMax} → ${vramCtxCap} to preserve GPU layer budget`);
          desiredMax = vramCtxCap;
          contextMin = Math.min(minBase, desiredMax);
        }
      }

      console.log(
        `[ChatEngine] Context sizing: train=${trainMaxContext}, hwCap=${hardwareCap} (source=${kvSourceMem}, kvBytesPerToken=${kvBytesPerToken}), user=${s.contextSize <= 0 ? 'auto' : s.contextSize}, test=${testMaxCtx || 'none'} → desiredMax=${desiredMax}`,
      );

      // Pre-flight validation: catch undefined variables before they cause runtime errors
      const _preflightVars = { kvBytesPerToken, hardwareCap, kvSourceMem, vramTotal, vramFree, trainMaxContext, totalLayersFromGguf, ggufArchMeta, desiredMax, contextMin, modelStats };
      for (const [name, val] of Object.entries(_preflightVars)) {
        if (val === undefined) {
          throw new Error(`Internal error: ${name} is undefined at loadModel. This is a bug — please report.`);
        }
      }

      const loadModelOpts = {
        modelPath,
        defaultContextFlashAttention: s.gpuPreference !== 'cpu',
        ignoreMemorySafetyChecks: true,
        useMmap: true,
        // Lock model pages in RAM to prevent OS from swapping them to disk (causes stalls)
        useMlock: os.totalmem() > modelStats.size * 2,
        onLoadProgress: (p) => {
          this.emit('status', { state: 'loading', message: `Loading model... ${Math.round(p * 100)}%`, progress: p });
        },
      };

      // KV cache quantization: resolve BEFORE loadModel so we can adjust fitContext.
      // Default 'f16' matches llama.cpp upstream and enables the fastest fused flash-attention
      // kernel path on consumer NVIDIA GPUs (this is what LM Studio / llama-server use). Lower
      // precision options (q8_0, q4_0, q4_1, q5_0, q5_1, q3_0) are user-selectable for trading
      // VRAM headroom against generation speed. 'currentQuant' lets node-llama-cpp match the
      // model's weight quantization (legacy behaviour, retained for explicit selection).
      const ALLOWED_KV_TYPES = new Set(['currentQuant', 'q3_0', 'q4_0', 'q4_1', 'q5_0', 'q5_1', 'q8_0', 'f16']);
      const rawKvType = rawLoadSettings.kvCacheType || 'q8_0';
      const kvCacheType = ALLOWED_KV_TYPES.has(rawKvType) ? rawKvType : undefined;

      if (s.gpuPreference === 'cpu') {
        loadModelOpts.gpuLayers = 0;
      } else if (s.gpuLayers >= 0) {
        loadModelOpts.gpuLayers = s.gpuLayers;
      } else {
        // Unified VRAM budget: pick gpuLayers + estimated context in one pass (Bug 4).
        const totalLayers = totalLayersFromGguf || 32;
        const budget = computeUnifiedVramBudget({
          vramFree,
          vramTotal,
          modelSizeBytes: modelStats.size,
          totalLayers,
          kvBytesPerToken: kvBytesPerToken || 0,
          desiredMaxContext: desiredMax,
          minContext: contextMin,
          gpuConstrainedContext: s.gpuConstrainedContext !== false,
          vramBalance: s.vramBalance,
          trainMaxContext: trainMaxContext ?? null,
        });
        const kvOnGpuFinal = (kvBytesPerToken || 0) * budget.contextSize * (budget.gpuLayers / totalLayers);
        const meta = budget.budgetMeta;
        const metaStr = meta
          ? `, mode=${meta.mode}, autoTarget=${meta.autoTarget}${meta.targetUsed != null ? `, targetUsed=${meta.targetUsed}` : ''}${meta.targetSteppedDown ? ', targetSteppedDown=true' : ''}${meta.cpuFallback ? ', cpuFallback=true' : ''}`
          : '';
        console.log(`[ChatEngine] Unified VRAM budget: vramFree=${(vramFree / 1e9).toFixed(2)}GB, vramTotal=${(vramTotal / 1e9).toFixed(2)}GB, gpuLayers=${budget.gpuLayers}/${totalLayers}, estCtx=${budget.contextSize}, kvOnGpu=${(kvOnGpuFinal / 1e6).toFixed(1)}MB, overhead=${(VRAM_GENERATION_OVERHEAD / 1e9).toFixed(2)}GB${metaStr}`);
        loadModelOpts.gpuLayers = budget.gpuLayers;
        this._preLoadContextEstimate = budget.contextSize;
      }

      this._model = await this._llama.loadModel(loadModelOpts);

      // P1: Use node-llama-cpp's cpuMathCores (probed by llama.cpp from actual CPU topology)
      // instead of os.cpus().length / 2 which was wrong on:
      //   - AMD Ryzen without SMT (formula halved usable cores)
      //   - Apple Silicon (no hyperthreading — formula halved usable cores)
      //   - Intel with E-cores (formula misclassified E-cores)
      // Falls back to os.cpus().length if cpuMathCores is missing or zero.
      const cpuMathCores = (typeof this._llama.cpuMathCores === 'number' && this._llama.cpuMathCores > 0)
        ? this._llama.cpuMathCores
        : os.cpus().length;
      const threadCount = Math.max(1, cpuMathCores);

      // P2: Adaptive batchSize from actual VRAM headroom after model load.
      // Larger batchSize = faster prompt processing (prefill). Output tok/s unchanged.
      // Measured free VRAM determines safe upper bound. CPU stays conservative.
      let vramFreeAfterModel = vramFree;
      if (s.gpuPreference !== 'cpu') {
        try {
          const vs = await this._llama.getVramState();
          vramFreeAfterModel = vs?.free || vramFree;
        } catch (e) { console.warn('[ChatEngine] VRAM query (batchSize) failed:', e.message); }
      }
      let batchSize;
      if (s.gpuPreference === 'cpu') batchSize = 512;
      else if (vramFreeAfterModel < 2 * 1024 * 1024 * 1024) batchSize = 1024;
      else if (vramFreeAfterModel < 4 * 1024 * 1024 * 1024) batchSize = 2048;
      else batchSize = 4096;
      console.log(`[ChatEngine] Perf: cpuMathCores=${cpuMathCores} (threads=${threadCount}), vramFreeAfterModel=${(vramFreeAfterModel/1e9).toFixed(2)}GB, batchSize=${batchSize}`);

      // P5: SWA models (Gemma, Mistral with sliding window) — set swaFullCache to enable
      // prefix reuse on multi-turn chats. Without this, multi-turn re-evaluates entire history.
      const swaSize = this._model?.fileInsights?.swaSize || 0;
      const swaFullCache = swaSize > 0;
      if (swaFullCache) console.log(`[ChatEngine] P5: SWA detected (swaSize=${swaSize}) — swaFullCache enabled for prefix reuse`);

      // Compute exact context size after model loading.
      // node-llama-cpp's createContext with { min, max } uses f16 for KV estimation,
      // which inflates 4x when using q4_0, causing all retries to fail and collapse
      // to the minimum (2048). We bypass this by computing the exact size ourselves
      // using actual post-load VRAM measurements and q4_0-aware KV estimates,
      // then passing a single number to createContext.
      const actualGpuLayers = this._model.gpuLayers || 0;
      const totalLayersForCtx = totalLayersFromGguf || 32;
      const gpuLayerRatio = totalLayersForCtx > 0 ? actualGpuLayers / totalLayersForCtx : 0;
      let computedCtxSize = desiredMax;

      if (kvBytesPerToken > 0 && s.gpuPreference !== 'cpu') {
        // Post-load: refine context using measured VRAM and locked gpuLayers (same unified budget).
        const postBudget = computeUnifiedVramBudget({
          vramFree: vramFreeAfterModel,
          vramTotal,
          modelSizeBytes: modelStats.size,
          totalLayers: totalLayersForCtx,
          kvBytesPerToken,
          desiredMaxContext: desiredMax,
          minContext: contextMin,
          gpuConstrainedContext: s.gpuConstrainedContext !== false,
          fixedGpuLayers: actualGpuLayers,
          trainMaxContext: trainMaxContext ?? null,
        });
        computedCtxSize = postBudget.contextSize;
        console.log(`[ChatEngine] Post-load unified context: vramFreeAfterModel=${(vramFreeAfterModel/1e9).toFixed(2)}GB, kvBpt=${kvBytesPerToken}, gpuRatio=${gpuLayerRatio.toFixed(2)}, computedCtxSize=${computedCtxSize}${this._preLoadContextEstimate != null ? `, preLoadEst=${this._preLoadContextEstimate}` : ''}`);
        this._preLoadContextEstimate = null;
      }

      // Build createContext options. Only attach experimentalKvCacheKeyType / ValueType when
      // the user has selected a non-f16 KV type. Passing 'f16' explicitly is supported by
      // node-llama-cpp but bypasses the upstream-default code path; omitting the override lets
      // llama.cpp pick the fastest fused flash-attention kernel for the model + GPU combination.
      const baseCtxOpts = {
        contextSize: computedCtxSize,
        flashAttention: s.gpuPreference !== 'cpu',
        ignoreMemorySafetyChecks: true,
        batchSize,
        threads: { ideal: threadCount, min: Math.max(1, threadCount - 1) },
        swaFullCache,
      };
      if (kvCacheType && kvCacheType !== 'f16' && kvCacheType !== 'q8_0') {
        baseCtxOpts.experimentalKvCacheKeyType = kvCacheType;
        baseCtxOpts.experimentalKvCacheValueType = kvCacheType;
      }
      this._baseCtxOpts = baseCtxOpts; // Save for summarizer VRAM reclaim

      // Create context with computed single-number size (bypasses f16-based fitting)
      try {
        this._context = await this._model.createContext(baseCtxOpts);
      } catch (ctxErr) {
        // Fallback: if a quantised KV type isn't actually applied by llama.cpp for this model,
        // the real KV size is f16 (up to 4x larger). Recompute with f16 estimate and retry.
        // vramFreeAfterModel was already measured above; reuse it.
        if (kvBytesPerToken > 0 && s.gpuPreference !== 'cpu') {
          const kvBytesF16 = kvBytesPerToken * 4;
          const fallbackBudget = computeUnifiedVramBudget({
            vramFree: vramFreeAfterModel,
            vramTotal,
            modelSizeBytes: modelStats.size,
            totalLayers: totalLayersForCtx,
            kvBytesPerToken: kvBytesF16,
            desiredMaxContext: desiredMax,
            minContext: contextMin,
            gpuConstrainedContext: s.gpuConstrainedContext !== false,
            fixedGpuLayers: actualGpuLayers,
            trainMaxContext: trainMaxContext ?? null,
          });
          const fallbackCtxSize = fallbackBudget.contextSize;
          console.warn(`[ChatEngine] Context creation at ${computedCtxSize} failed (${ctxErr.message}), retrying with f16 KV estimate: ${fallbackCtxSize}`);
          const fallbackOpts = { ...baseCtxOpts, contextSize: fallbackCtxSize };
          this._context = await this._model.createContext(fallbackOpts);
        } else {
          throw ctxErr;
        }
      }

      // Diagnostic: verify context creation
      const actualCtxSize = this._context?.contextSize;
      console.log(`[ChatEngine] Context created: ctx=${actualCtxSize}, gpuLayers=${actualGpuLayers}, flashAttn=${s.gpuPreference !== 'cpu'}, batchSize=${batchSize}, threads=${threadCount}, swaFullCache=${swaFullCache}, kvCacheType=${kvCacheType || 'default'}, requestedSize=${computedCtxSize}`);
      const loadVramBal = s.vramBalance || 'balanced';
      const loadPresetNote = loadVramBal === 'speed'
        ? ' — Speed preset maximizes GPU layers; context is whatever fits remaining VRAM'
        : '';
      console.log(
        `[ChatEngine] Load budget: preset=${loadVramBal}, gpuLayers=${actualGpuLayers}/${totalLayersForCtx}, ctx=${actualCtxSize}, kvBpt=${kvBytesPerToken || 0}, vramFreeAfterLoad=${(vramFreeAfterModel / 1e9).toFixed(2)}GB${loadPresetNote}`,
      );

      // Graceful context degradation: log exact reason and suggest action
      const ctxDegradation = actualCtxSize < desiredMax * 0.8;
      if (ctxDegradation) {
        const ratio = actualCtxSize / desiredMax;
        const reason = ratio < 0.1
          ? `Context collapsed to ${actualCtxSize} (${(ratio * 100).toFixed(1)}% of desired ${desiredMax}). Likely cause: GPU layers consumed too much VRAM, leaving none for KV cache.`
          : `Context reduced to ${actualCtxSize} (${(ratio * 100).toFixed(1)}% of desired ${desiredMax}). GPU layers (${actualGpuLayers}) may be consuming VRAM needed for KV cache.`;
        const suggestion = actualGpuLayers > 0
          ? `Try: reduce GPU layers in settings, or set a smaller context size manually.`
          : `Try: increase context size in settings, or switch to a smaller model.`;
        console.warn(`[ChatEngine] Context degradation: ${reason} ${suggestion}`);
      }

      this._sequence = this._context.getSequence();

      const actualCtx = this._context.contextSize || 0;
      // Estimate parameter count from GGUF metadata or filename (e.g. "Qwen3.5-4B" → 4B)
      let paramCount = ggufArchMeta?.totalParameterCount || null;
      if (!paramCount) {
        const sizeMatch = path.basename(modelPath).match(/(\d+(?:\.\d+)?)\s*[Bb]/);
        if (sizeMatch) paramCount = Math.round(parseFloat(sizeMatch[1]) * 1e9);
      }
      this.modelInfo = {
        path: modelPath,
        name: path.basename(modelPath),
        size: modelStats.size,
        parameterCount: paramCount,
        contextSize: actualCtx,
        contextSizeRequested: s.contextSize <= 0 ? 'auto' : s.contextSize,
        contextSizeCap: desiredMax,
        contextTrainMax: trainMaxContext,
        contextHardwareCap: hardwareCap,
        kvBytesPerToken: kvBytesPerToken,
        kvMemSource: kvSourceMem,
        totalLayers: totalLayersFromGguf != null ? totalLayersFromGguf : undefined,
        gpuLayers: this._model.gpuLayers || 0,
        gpuMode: s.gpuPreference === 'cpu' ? false : 'auto',
        vramFreeAfterLoadGB: Number((vramFreeAfterModel / 1e9).toFixed(2)),
        contextPctOfCap: desiredMax > 0 ? Math.round((actualCtx / desiredMax) * 100) : undefined,
        vramBalance: loadVramBal,
        totalLayers: totalLayersForCtx,
      };

      // ─── Three-Tier Model Profile Resolution ───
      // Tier 1: GGUF metadata auto-detection (what the file tells us about itself)
      // Tier 2: Vendor profile overrides (curated settings from model vendor documentation)
      // Tier 3: BASE_DEFAULTS (neutral fallback when neither source provides info)
      //
      // This system is future-proof: a brand-new model with an unknown architecture
      // string and unknown filename will still work correctly because Tier 1 detects
      // capabilities directly from the GGUF file's embedded chat template, and Tier 3
      // provides neutral defaults. Vendor profiles (Tier 2) are optional enhancements
      // that optimize sampling for families with documented vendor recommendations.

      // Tier 1: Auto-detect thinking support from the GGUF chat template.
      // The Jinja chat template is embedded in every GGUF file under tokenizer.chat_template.
      // If it contains `enable_thinking` as a variable, the model supports thinking mode.
      // This is future-proof: any model that adds thinking will include this variable.
      // No manual profile entry is required for thinking to work on new models.
      const _templateSupportsThinking = ggufChatTemplate
        ? /enable_thinking/.test(ggufChatTemplate)
        : false;
      this._templateSupportsThinking = _templateSupportsThinking;
      console.log(`[ChatEngine] Tier 1: chat_template auto-detect — templatePresent=${!!ggufChatTemplate}, supportsThinking=${_templateSupportsThinking}`);

      // Tier 2: Family detection — GGUF architecture metadata (primary) then filename (fallback).
      // GGUF metadata.general.architecture is authoritative (e.g. "chatglm", "qwen35", "gemma3").
      // Filename detection is kept as fallback for corrupted/missing metadata.
      const _archFamily = detectFamilyFromArch(ggufArchString);
      const _fileFamily = detectFamily(modelPath);
      const _detectedFamily = _archFamily || _fileFamily;
      const _detectedSizeB = paramCount ? paramCount / 1e9 : detectParamSize(modelPath);
      this._modelProfile = getModelProfile(ggufArchString || _detectedFamily, _detectedSizeB);

      // Merge Tier 1 auto-detection into the profile.
      // Template wins when it declares enable_thinking but profile says none.
      // When template lacks enable_thinking, instruct-family profiles are downgraded to none
      // (native-segment families deepseek/qwen/glm/gemma keep profile budget for segment API).
      const _profileThinkMode = this._modelProfile?.thinkTokens?.mode;
      if (_templateSupportsThinking && _profileThinkMode === 'none') {
        // Template says thinking is supported but profile says none — template wins
        this._modelProfile.thinkTokens.mode = 'budget';
        this._modelProfile.thinkTokens.budget = this._modelProfile.thinkTokens.budget || 2048;
        console.log(`[ChatEngine] Tier 1 override: chat_template supports thinking but profile said 'none' — upgraded to 'budget'`);
      } else if (_templateSupportsThinking && _profileThinkMode !== 'budget' && _profileThinkMode !== 'strip') {
        // Unknown model with template thinking support — activate budget mode
        this._modelProfile.thinkTokens.mode = 'budget';
        this._modelProfile.thinkTokens.budget = this._modelProfile.thinkTokens.budget || 2048;
        console.log(`[ChatEngine] Tier 1 auto-detect: chat_template supports thinking — set thinkTokens.mode='budget'`);
      } else if (!_templateSupportsThinking && _profileThinkMode !== 'none') {
        // Instruct models (phi, llama, mistral, etc.) must not get thought budgets when the
        // GGUF chat template has no enable_thinking variable. Native-segment families keep budget.
        const _NATIVE_THINK_FAMILIES = new Set(['deepseek', 'qwen', 'glm', 'gemma']);
        if (!_NATIVE_THINK_FAMILIES.has(_detectedFamily)) {
          this._modelProfile.thinkTokens.mode = 'none';
          this._modelProfile.thinkTokens.budget = 0;
          console.log(`[ChatEngine] Template has no enable_thinking — disabled think budget for instruct family '${_detectedFamily}'`);
        }
      }

      // Pass enable_thinking to chat template kwargs ONLY when the GGUF template declares it.
      // Never pass enable_thinking=true to instruct models whose templates lack the variable
      // (e.g. Phi-4-mini-instruct) — that corrupts generation and wastes context on fake "thinking".
      const _resolvedThinkMode = this._modelProfile?.thinkTokens?.mode;
      this._thinkingCapable = _resolvedThinkMode !== 'none';
      const _chatTemplateKwargs = {};
      const _thinkingModeForcedOff = s.thinkingMode === 'off';
      if (s.enableThinking && !_thinkingModeForcedOff && _templateSupportsThinking && _resolvedThinkMode !== 'none') {
        _chatTemplateKwargs.enable_thinking = true;
      } else {
        _chatTemplateKwargs.enable_thinking = false;
      }
      this._chatTemplateKwargs = _chatTemplateKwargs;
      this._ggufChatTemplate = ggufChatTemplate;

      // LlamaChatOptions has no chatTemplateKwargs field — passing it to the constructor
      // was silently ignored. Only override 'auto' when we must wire enable_thinking into
      // Jinja additionalRenderParameters. All other models keep node-llama-cpp auto resolution
      // (QwenChatWrapper, DeepSeekChatWrapper, etc.) unchanged.
      let chatWrapperOpt = 'auto';
      const needsThinkingJinja = ggufChatTemplate && _templateSupportsThinking && _chatTemplateKwargs.enable_thinking;
      this._currentThinkingMode = s.thinkingMode;

      if (needsThinkingJinja && s.thinkingMode !== 'auto') {
        const jinjaOpts = {
          template: ggufChatTemplate,
          tokenizer: this._model.tokenizer,
          additionalRenderParameters: { ..._chatTemplateKwargs, enable_thinking: s.thinkingMode !== 'off' },
          segments: {
            thoughtTemplate: '<think>{{content}}</think>',
            reopenThoughtAfterFunctionCalls: false,
          },
        };
        try {
          if (s.thinkingMode === 'B' || s.thinkingMode === 'off') {
            chatWrapperOpt = new JinjaTemplateChatWrapper(jinjaOpts);
            console.log(`[ChatEngine] Custom Jinja wrapper (mode ${s.thinkingMode}, no prefix injection): enable_thinking=${s.thinkingMode !== 'off'}`);
          } else {
            // Mode C (default): ThinkingOpenJinjaChatWrapper with noPrefixTrigger
            chatWrapperOpt = new ThinkingOpenJinjaChatWrapper(jinjaOpts);
            const thoughtSeg = chatWrapperOpt.settings?.segments?.thought;
            console.log(`[ChatEngine] Custom Jinja wrapper (mode C, thought open at gen start): enable_thinking=true, thoughtSegment=${!!thoughtSeg}`);
          }
        } catch (jinjaErr) {
          console.warn(`[ChatEngine] Custom Jinja wrapper failed — falling back to auto: ${jinjaErr.message}`);
          chatWrapperOpt = 'auto';
        }
      } else {
        console.log(`[ChatEngine] chatWrapper=auto (mode=${s.thinkingMode}); enable_thinking=${_chatTemplateKwargs.enable_thinking}`);
      }
      this._chatWrapper = chatWrapperOpt;
      this._jinjaThoughtSegments = false; // retired — retroactive handler removed
      this._chat = new LlamaChat({ contextSequence: this._sequence, chatWrapper: chatWrapperOpt });
      console.log(`[ChatEngine] chatTemplateKwargs=${JSON.stringify(_chatTemplateKwargs)}, wrapper=${chatWrapperOpt === 'auto' ? 'auto' : chatWrapperOpt.wrapperName}, resolvedThinkMode=${_resolvedThinkMode}, enableThinking=${s.enableThinking}, templateSupportsThinking=${_templateSupportsThinking}`);

      this._chatHistory = [{ type: 'system', text: SYSTEM_PROMPT }];
      this._lastEvaluation = null;
      this.modelInfo.family = _detectedFamily;
      this.modelInfo.sizeB = _detectedSizeB;
      this.modelInfo.tier = this._modelProfile._meta.tier;
      this.modelInfo.sampling = this._modelProfile.sampling;
      console.log(`[ChatEngine] P3: Model profile resolved — arch=${ggufArchString || 'n/a'}, family=${_detectedFamily}, source=${this._modelProfile._meta.source || this._modelProfile._meta.profileSource}, sizeB=${_detectedSizeB.toFixed(2)}, tier=${this._modelProfile._meta.tier}, sampling=${JSON.stringify(this._modelProfile.sampling)}`);

      this.currentModelPath = modelPath;
      this.isReady = true;
      this.isLoading = false;
      this._loadState = 'ready';
      streamTrace.trace('stream', 'model-load-complete', {
        modelPath,
        modelInfo: { ...this.modelInfo },
        contextSize: this._context?.contextSize,
        gpuLayers: this._model?.gpuLayers,
        vramFreeAfterModelGB: (vramFreeAfterModel / 1e9).toFixed(3),
        batchSize,
        threadCount,
      });

      // Check vision availability — do NOT auto-start. Vision starts on-demand when an image needs captioning.
      try {
        const visionCheck = visionServer.checkAvailability(modelPath, {
          embeddingLength: ggufArchMeta?.embedding_length ?? null,
        });
        if (visionCheck.available) {
          console.log(`[ChatEngine] Vision: mmproj found at ${visionCheck.mmprojPath} — vision available (will start on first image)`);
          this.modelInfo.visionAvailable = true;
        } else {
          console.log(`[ChatEngine] Vision: ${visionCheck.reason} — vision unavailable for this model`);
          this.modelInfo.visionAvailable = false;
        }
      } catch (visionErr) {
        console.error(`[ChatEngine] Vision check error: ${visionErr.message}`);
        this.modelInfo.visionAvailable = false;
      }

      console.log(
        `[ChatEngine] Model ready: ctx=${actualCtx} (${s.contextSize <= 0 ? 'auto' : `fixed ${s.contextSize}`}, cap ${desiredMax}${trainMaxContext != null ? `, train ${trainMaxContext}` : ''}), gpuLayers=${this.modelInfo.gpuLayers}`,
      );

      this.emit('status', { state: 'ready', message: `Model ready: ${this.modelInfo.name}`, modelInfo: this.modelInfo });
      return this.modelInfo;
    } catch (err) {
      this.isLoading = false;
      this.isReady = false;
      this._loadState = 'idle';
      // Detect "unknown model architecture" failures from llama.cpp and surface
      // an actionable message instead of the raw C++ error. Matches messages like:
      //   "unknown model architecture: 'gemma4'"
      //   "unknown architecture 'qwen3'"
      // The bundled llama.cpp build only knows the architectures present at the
      // node-llama-cpp release time. New model families (e.g. gemma4 released
      // after our build) cannot be loaded until the runtime is updated.
      const archMatch = /unknown\s+(?:model\s+)?architecture[:\s]*['"]?([A-Za-z0-9_.-]+)['"]?/i.exec(err.message || '');
      let userMessage = err.message;
      if (archMatch) {
        const arch = archMatch[1];
        userMessage =
          `Model architecture "${arch}" is not supported by the bundled llama.cpp runtime. ` +
          `Update guIDE to a newer release, or rebuild the runtime with ` +
          `'npx -n node-llama-cpp source download --release latest'. ` +
          `(Original error: ${err.message})`;
        console.error(`[ChatEngine] Unsupported architecture detected: ${arch}`);
      }
      this.emit('status', { state: 'error', message: userMessage });
      if (rollback) {
        console.warn(`[ChatEngine] Load failed — restoring previous model: ${rollback.path}`);
        try {
          await this._doInitialize(rollback.path, rollback.settings, { isRollback: true });
          console.log('[ChatEngine] Rollback restore OK');
        } catch (rollbackErr) {
          console.error(`[ChatEngine] Rollback restore failed: ${rollbackErr.message}`);
        }
      }
      throw err;
    }
  }

  // Redact passwords/credentials from text before storing in chat history
  _redactCredentials(text) {
    console.log(`[ChatEngine] _redactCredentials: input=${text?.length || 0} chars`);
    if (!text || typeof text !== 'string') return text;
    const redacted = text
      .replace(/(?:password|passwd|pwd|secret|token|api[_-]?key)\s*[:=]\s*["']?([^\s"'`,;}\]]{3,})/gi,
        (m, val) => m.replace(val, '[REDACTED]'))
      .replace(/(?:password|passwd|pwd|secret|token|api[_-]?key)["']\s*:\s*["']([^"']{3,})["']/gi,
        (m, val) => m.replace(val, '[REDACTED]'));
    console.log(`[ChatEngine] _redactCredentials: redacted=${redacted.length} chars`);
    return redacted;
  }

  async chat(userMessage, options = {}) {
    if (this._activeChatPromise) {
      console.log('[ChatEngine] chat() awaiting prior in-flight generation');
      try { await this._activeChatPromise; } catch (_) { /* prior turn may have failed or been cancelled */ }
    }
    const run = this._chatUnserialized(userMessage, options);
    this._activeChatPromise = run;
    try {
      return await run;
    } finally {
      if (this._activeChatPromise === run) this._activeChatPromise = null;
    }
  }

  async _chatUnserialized(userMessage, options = {}) {
    if (this._loadState === 'loading' || this._loadState === 'disposing') {
      throw new Error('Model is loading — please wait a moment and try again.');
    }
    if (!this.isReady || !this._chat) throw new Error('Model not ready');

    const { onToken, onComplete, onContextUsage, onToolCall, onStreamEvent, systemPrompt, functions, toolPrompt, compactToolPrompt, compactToolParts, executeToolFn, guideInstructionsPath, getCancelled } = options;
    this._enableContextSummarizer = options.enableContextSummarizer !== false;
    const isCancelled = () => (typeof getCancelled === 'function' && getCancelled()) || this.isCancelled();
    const _streamDiag = !!options.debugStreamDiag;
    const _traceOn = options.streamTraceEnabled === true;
    const _traceLevel = options.streamTraceLevel || 'tokens';
    const _traceFull = _traceOn && _traceLevel === 'full';
    const _TOKEN_TRACE_EVTS = new Set(['token-prose', 'token-response-chunk', 'sf-content-token-emit']);
    const _logStreamDiag = (...args) => { if (_streamDiag) console.log(...args); };
    const _trace = (evt, fields) => {
      if (!_traceOn) return;
      if (_traceLevel === 'tokens' && !_TOKEN_TRACE_EVTS.has(evt)) return;
      streamTrace.trace('stream', evt, fields);
    };

      // Inject attachment content into user message
      const attachments = Array.isArray(options.attachments) ? options.attachments : [];
      let effectiveUserMessage = String(userMessage ?? '');
      this._recentlyWrittenFiles.clear(); // reset per chat() call
      this._consecutiveToolsWithoutTodoUpdate = 0;
      this._toolRoundCount = 0;
      console.log(`[ChatEngine] ═══ USER MESSAGE ═══ "${String(userMessage)}"`);
      if (attachments.length > 0) {
        console.log(`[ChatEngine] Attachments: ${attachments.length} (${attachments.map(a => `${a.name||'?'} ${a.mimeType||a.type||'?'}`).join(', ')})`);
      }
      console.log(`[ChatEngine] Processing ${attachments.length} attachment(s)`);
      if (attachments.length > 0) {
        const textParts = [];
        for (let ai = 0; ai < attachments.length; ai++) {
          const a = attachments[ai];
          console.log(`[ChatEngine] Attachment #${ai}: name=${a?.name || '?'}, mime=${a?.mimeType || a?.type || '?'}, hasData=${!!a?.data}`);
          if (!a?.data) {
            console.warn(`[ChatEngine] Attachment #${ai} has no data — skipping`);
            continue;
          }
          const mime = (a.mimeType || a.type || '').toLowerCase();
          if (mime.startsWith('image/')) {
            console.log(`[ChatEngine] Attachment #${ai} is image, visionAvailable=${!!this.modelInfo?.visionAvailable}`);
            // Vision captioning: captionImage() handles load-on-demand internally
            // (starts server if needed, captions, then unloads to free VRAM)
            let captioned = false;
            if (this.modelInfo?.visionAvailable) {
              console.log(`[ChatEngine] Calling visionServer.captionImage for attachment #${ai}`);
              try {
                const caption = await visionServer.captionImage(
                  a.data, mime,
                  'Describe this image in detail. List all visible text, UI elements, content, and any information shown.'
                );
                if (caption) {
                  textParts.push(`[VISION ANALYSIS — You have already seen this image via your vision system. This is what you observed:\n${caption}\nEND VISION ANALYSIS]`);
                  console.log(`[ChatEngine] Image attachment #${ai} captioned: ${caption.length} chars`);
                  captioned = true;
                } else {
                  console.warn(`[ChatEngine] visionServer.captionImage returned empty caption for attachment #${ai}`);
                }
              } catch (visionErr) {
                console.error(`[ChatEngine] Vision caption for attachment #${ai} failed: ${visionErr.message}`);
              }
            } else {
              console.warn(`[ChatEngine] Vision not available for attachment #${ai} — skipping caption`);
            }
            if (!captioned) {
              // Vision unavailable — tell the model explicitly that the image cannot be processed.
              // Do NOT inject raw attachment metadata like "[Attached context] filename.png"
              // because the model echoes it verbatim as its response instead of answering the user.
              console.log(`[ChatEngine] Attachment #${ai} not captioned — injecting fallback message`);
              textParts.push(`[Image attachment "${a.name || 'image'}" could not be processed by vision engine. Tell the user you cannot see the image and ask them to describe its contents.]`);
            }
            continue;
          }
          try {
            const decoded = Buffer.from(a.data, 'base64').toString('utf8');
            textParts.push(`[Attached file: ${a.name || 'file'}]\n${decoded}`);
            console.log(`[ChatEngine] Attachment #${ai} decoded as text: ${decoded.length} chars`);
          } catch (e) {
            console.warn(`[ChatEngine] Attachment #${ai} decode failed: ${e.message}`);
          }
        }
        if (textParts.length > 0) {
          effectiveUserMessage = effectiveUserMessage + '\n\n' + textParts.join('\n\n---\n\n');
          console.log(`[ChatEngine] Final effectiveUserMessage length: ${effectiveUserMessage.length} chars`);
        } else {
          console.warn(`[ChatEngine] No text parts produced from ${attachments.length} attachment(s)`);
        }
      }

    // ─── Context Assembly Pipeline (6-layer ordered injection) ───
    // Same architecture as Windsurf Cascade: Rules → Memories → Editor → RAG → Tools → History
    // Each layer is appended in order so the model sees them in priority sequence.
    const contextTokens = this._context?.contextSize || 8192;
    const resolvedMode = resolveAgentMode({
      askOnly: options.askOnly,
      planMode: options.planMode,
      chatMode: options.chatMode,
      agentPhase: options.agentPhase,
      toolsEnabled: options.toolsEnabled !== false,
      planReady: !!options.planReady,
      planFileExists: !!options.planFileExists,
    });
    streamTrace.trace('stream', 'agent-mode-resolved', {
      askOnly: resolvedMode.askOnly,
      planMode: resolvedMode.planMode,
      planning: resolvedMode.planning,
      building: resolvedMode.building,
      planPhase: resolvedMode.planPhase,
      toolsActive: resolvedMode.toolsActive,
      allowedTools: resolvedMode.allowedTools ? [...resolvedMode.allowedTools] : null,
    });
    let basePrompt = systemPrompt || resolvedMode.baseSystemPrompt;

    // Layer 1: Mode-specific system prompt (agent / plan / ask base — not shared)
    if (resolvedMode.systemPromptAdditions) {
      basePrompt += resolvedMode.systemPromptAdditions;
    }
    const _modeLabel = resolvedMode.askOnly ? 'ask' : resolvedMode.planning ? 'plan' : resolvedMode.building ? 'build' : 'agent';
    console.log(`[ChatEngine] Prompt base: mode=${_modeLabel}, planPhase=${resolvedMode.planPhase || 'n/a'}, baseChars=${resolvedMode.baseSystemPrompt.length}`);

    // Layer 2–3: Project rules, environment, editor context (shared with cloud via buildAgentSystemPromptLayers)
    basePrompt += buildAgentSystemPromptLayers({
      projectPath: this._projectPath,
      guideInstructionsPath,
      editorContext: this._ctx?.editorContext,
      editorDiagnostics: this._ctx?.editorDiagnostics,
    });
    const customInstructions = options.customInstructions;
    if (customInstructions && customInstructions.trim()) {
      basePrompt += `\n\n## Custom Instructions\n${customInstructions.trim()}`;
    }
    if (resolvedMode.askOnly) {
      console.log('[ChatEngine] Ask mode — tool prompt suppressed, model responds conversationally');
    } else if (resolvedMode.building) {
      console.log('[ChatEngine] Build phase — implement in project root, not .guide/');
    } else if (resolvedMode.planning) {
      console.log(`[ChatEngine] Plan mode — planPhase=${resolvedMode.planPhase}`);
    }

    // Layer 4: Tool prompt (available tools and their descriptions)
    // Hoist useCompact and effectiveToolPrompt so they're accessible in the
    // generation-space trimming section (line ~1746) regardless of which
    // branch sets them. Without this, ReferenceError when toolPrompt is absent.
    let useCompact = false;
    let effectiveToolPrompt = '';

    const _toolsEnabled = options.toolsEnabled !== false;
    console.log(`[ChatEngine] chat() toolsEnabled=${_toolsEnabled} thinkingMode=${this._currentThinkingMode} options.toolsEnabled=${options.toolsEnabled}`);
    if (!_toolsEnabled) {
      console.log('[ChatEngine] Tools disabled by setting — skipping tool prompt and native FC');
      this._chatHistory[0].text = basePrompt;
    } else if (options.askOnly) {
      // Ask mode: no tools available — just set the base prompt with mode instruction
      this._chatHistory[0].text = basePrompt;
    } else if (toolPrompt) {
      const historyChars = this._chatHistory.slice(1).reduce((sum, m) => sum + (String(m.text || '').length), 0);
      const userMessageChars = effectiveUserMessage.length;
      const agentMode = _toolsEnabled && !options.askOnly;
      const agentSizeTier = this._modelProfile?._meta?.tier || 'large';
      const preferCompactCatalog = agentMode && shouldPreferCompactToolCatalog({
        contextTokens,
        basePromptChars: basePrompt.length,
        historyChars,
        userMessageChars,
        fullToolPromptChars: toolPrompt?.length || 0,
        sizeTier: agentSizeTier,
      });
      const budgetResult = buildBudgetProportionalToolPrompt({
        contextTokens,
        basePromptChars: basePrompt.length,
        historyChars,
        userMessageChars,
        toolPrompt,
        compactToolParts,
        compactToolPrompt,
        agentMode,
        agentMinToolPromptChars: resolveAgentMinToolPromptChars(agentSizeTier),
        preferCompactCatalog,
      });
      effectiveToolPrompt = budgetResult.prompt;
      useCompact = budgetResult.mode !== 'full';

      if (agentMode && budgetResult.tier0Ok === false) {
        console.error('[ChatEngine] Agent mode tool prompt missing Tier-0 Browser tools — catalog truncated');
        if (onStreamEvent) {
          onStreamEvent('generation-warning', {
            message: 'Tool catalog truncated — Browser tools may be missing. Start a new session or reduce context pressure.',
            suggestion: 'History was too large; shift conversation or open a fresh session.',
          });
        }
      }

      const finalPct = Math.round((budgetResult.usedTokens / contextTokens) * 100);
      const toolPromptTokens = Math.ceil(toolPrompt.length / TOOL_PROMPT_CHARS_PER_TOKEN);
      const toolPct = Math.round((toolPromptTokens / contextTokens) * 100);

      if (toolPct > 50 && onStreamEvent && budgetResult.mode === 'full') {
        onStreamEvent('generation-warning', {
          message: `Full tool catalog would use ${toolPct}% of context (${toolPromptTokens.toLocaleString()}/${contextTokens.toLocaleString()} tokens)`,
          suggestion: 'Using budget-proportional tool list. Try a smaller model, reduce context in settings, or start a new session.',
        });
      }

      this._chatHistory[0].text = basePrompt + '\n\n' + effectiveToolPrompt;
      console.log(`[ChatEngine] Tool prompt injected (${effectiveToolPrompt.length} chars, mode=${budgetResult.mode}, budget=${budgetResult.budgetTokens} tok, ctx=${contextTokens}, finalPct=${finalPct}%, parts=${budgetResult.partsUsed ?? 'n/a'}, tier0Ok=${budgetResult.tier0Ok})`);
      console.log(`[ChatEngine] Prompt assembly: systemChars=${basePrompt.length}, toolChars=${effectiveToolPrompt.length}, totalSystemChars=${basePrompt.length + effectiveToolPrompt.length}, historyMsgs=${this._chatHistory.length - 1}`);
    } else if (functions && Object.keys(functions).length > 0) {
      this._chatHistory[0].text = basePrompt + this._buildToolPrompt(functions);
      console.log(`[ChatEngine] Functions provided (fallback): ${Object.keys(functions).length} tools`);
    } else if (systemPrompt) {
      this._chatHistory[0].text = systemPrompt;
    } else {
      // No tool prompt, functions, or custom systemPrompt — set basePrompt directly
      this._chatHistory[0].text = basePrompt;
    }

    if (this._pendingUserMessage) {
      console.warn('[ChatEngine] Clearing stale _pendingUserMessage at chat() start');
      this._pendingUserMessage = null;
    }

    this._chatHistory.push({ type: 'user', text: effectiveUserMessage });
    console.log(`[ChatEngine] chat() generation START: userMsg=${effectiveUserMessage.length} chars, history=${this._chatHistory.length} msgs`);

    this._abortController = new AbortController();
    this._cancelRequested = false;
    this._toolExecFingerprints = [];
    let fullResponse = '';
    let visibleResponse = '';
    let _proseLogBuf = '';
    let _thinkLogBuf = '';
    let tokensSinceLastUsageReport = 0;
    let totalToolCalls = 0;
    const genStartTime = Date.now();
    let genTokenCount = 0;
    let totalGenTokens = 0; // counts ALL tokens: prose + thinking + FC grammar (genTokenCount only counts prose)
    let _chatStopReason = null;

    try {
      console.log(`[ChatEngine] chat() try block ENTER: abortController=${!!this._abortController}`);
      // ── Streaming tool call filter ──
      // Two-layer suppression of tool call JSON from the UI:
      //
      // Layer 1 (real-time): This filter processes each token character-by-character.
      //   - When `{` appears at a line boundary, buffer it. If `"tool":` appears
      //     within the first 80 chars, keep buffering silently until braces close.
      //   - When ``` appears at a line boundary, enter fence mode. If the fence
      //     content starts with `{` and contains `"tool":`, suppress the entire fence.
      //
      // Layer 2 (post-generation): stripToolCallText() catches anything the
      //   streaming filter missed (e.g., XML <tool_call> tags).
      //
      // Result: tool call JSON never appears in the chat as raw text.

      let _sfBuf = '';           // pending buffer
      let _sfDepth = 0;         // brace depth
      let _sfActive = false;    // inside a potential raw JSON tool call
      let _sfConfirmed = false; // buffer confirmed to contain "tool":
      let _sfInStr = false;     // inside a JSON string
      let _sfEscaped = false;   // previous char was backslash inside string
      let _sfLastCharWasNewlineOrStart = true;

      // Fence tracking: ```json ... ```
      let _sfInFence = false;    // inside a code fence
      let _sfFenceBuf = '';      // accumulated fence content (markers + body)
      let _sfFenceTickCount = 0; // tracks consecutive backticks
      let _sfPendingFenceOpen = false; // defer fence open until header line completes (glued ``` prose)
      let _sfPendingFenceLine = '';
      let _sfSwallowFenceDebris = false; // swallow orphan ``` after tool-json fence close
      let _sfDebrisBuf = '';
      /** When true, fence body is plain markdown code (html, etc.) — stream to UI instead of buffering until ``` */
      let _sfFenceStreamPlain = false;
      let _sfFencePlainTick = 0; // backticks while streaming plain fence (closing ```)
      let _sfFencePlainHeader = ''; // header through newline — kept when aborting plain → buffer
      let _sfFencePlainBody = ''; // body chars forwarded or pending abort re-check

      // Real-time file content streaming state — detects write_file/create_file/append_to_file
      // content fields inside tool call JSON and streams them to the UI as they arrive
      let _sfFileWriteDetected = false;
      let _sfToolCallNotified = false;  // tracks whether tool-generating event was emitted for current fence
      let _sfToolGeneratingStart = 0;
      let _sfLastToolProgressAt = 0;
      let _sfContentStreamActive = false;
      let _sfContentDone = false;
      let _sfContentEsc = false;
      let _sfContentBuf = '';
      let _sfContentFilePath = '';
      let _sfContentOldText = '';
      let _sfStreamIsEdit = false;
      let _sfUnicodeCount = 0;
      let _sfUnicodeChars = '';
      let _sfContentJsonState = _createJsonStringStreamState();
      let _sfFenceStreamedLen = 0;
      let _sfFenceContentStreaming = false;

      const _sfContentStreamInProgress = () => (
        _sfContentStreamActive
        || _sfFenceContentStreaming
        || _sfContentJsonState.quotePending
        || _sfContentJsonState.escPending
        || _sfContentJsonState.unicodeCount > 0
      );

      /** Block fence-close ``` tick count only during char-FSM escape states — not fence-delta streaming. */
      const _sfFenceCloseTickBlocked = () => (
        _sfContentStreamActive
        || _sfContentJsonState.quotePending
        || _sfContentJsonState.escPending
        || _sfContentJsonState.unicodeCount > 0
      );

      const _sfResetContentJsonState = () => {
        _sfContentJsonState = _createJsonStringStreamState();
        _sfContentEsc = false;
        _sfUnicodeCount = 0;
        _sfUnicodeChars = '';
      };

      const _sfProcessContentStreamChar = (ch, phase) => {
        const step = _jsonStringStreamStep(ch, _sfContentJsonState);
        _sfContentJsonState = step.state;
        _sfContentEsc = step.state.escPending;
        _sfUnicodeCount = step.state.unicodeCount;

        if (step.out) _sfContentBuf += step.out;

        if (step.ended) {
          _sfContentStreamActive = false;
          _sfContentDone = true;
          if (_sfContentBuf && onStreamEvent) {
            _trace('sf-content-token-emit', { filePath: _sfContentFilePath, text: _sfContentBuf, phase: `${phase}-flush` });
            onStreamEvent('file-content-token', _sfContentBuf);
            _sfContentBuf = '';
          }
          const reason = step.endReason === 'structural-close'
            ? `${phase}-structural-close`
            : `${phase}-close-quote`;
          if (onStreamEvent) {
            _trace('sf-content-end', { reason, filePath: _sfContentFilePath, sf: _traceSfState() });
            onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _normalizePath(_sfContentFilePath) });
            _sfContentEndCompleted.add(_normalizePath(_sfContentFilePath));
            _sfMarkFileContentStreamActive(null);
          }
          return;
        }

        if (_sfContentStreamActive && _sfContentBuf.length >= 1) {
          if (onStreamEvent) {
            _trace('sf-content-token-emit', { filePath: _sfContentFilePath, text: _sfContentBuf, phase });
            onStreamEvent('file-content-token', _sfContentBuf);
            _sfContentBuf = '';
          }
        }
      };

      // enableThinkingFilter — when true, suppress thinking tokens from UI output
      const _thinkingFilterEnabled = !!options.enableThinkingFilter;
      // Raw <think> tag parser for all thinking-capable templates. Per-chunk B4 suppresses
      // when native onResponseChunk thought segments are active (_sfNativeThinkActive). GLM Jinja often
      // emits tags via onTextChunk without segment events — disabling the parser here caused tag leaks.
      const _sfRawThinkTagsEnabled = !!this._templateSupportsThinking;

      // Think-tag tracking for reasoning models.
      // These models output <think>...</think> in raw text (LlamaCompletion mode).
      // Without detection, thinking text gets sent as regular prose to the UI.
      // We track <think> open/close tags and route thinking content to llm-thinking-token events
      // so it appears in thinking blocks instead of as regular prose.
      let _sfInThink = false;       // currently inside <think>...</think>
      let _sfThinkBuf = '';         // buffer for detecting <think> and </think> tags across chunk boundaries
      let _sfThinkTagMatch = '';    // partial match for think tags
      // B4: When the chat wrapper emits thinking via native onResponseChunk segments
      // (Qwen, DeepSeek-R1, etc.), suppress raw-text <think> detection to avoid double-emit.
      // Flag flips true on the first native segment observed in this generation.
      let _sfNativeThinkActive = false;
      let _sfNativeThinkChars = 0; // B03: native thought segment chars (not in fullResponse)
      let nativeThinkFullText = ''; // accumulates native segment thinking text for logging
      const _sfStreamedFileWrites = new Set();
      const _sfProsedFileWrites = new Set(); // files whose write_file JSON was flushed as prose (not streamed)
      // Canonicalize paths for dedup — backslashes→forward-slashes, collapse dupes, lowercase drive letter.
      const _normalizePath = (p) => resolveStreamingFileKey(p, this._projectPath);
      let _sfVisibleChars = 0; // tracks chars forwarded to frontend (after filter removes tool JSON)
      let _sfFenceInThink = false; // fence that opened inside think mode
      let _sfEarlyFileStartEmitted = false;
      let _sfContentContinuation = null;
      const _sfContentEndCompleted = new Set();
      let _sfAgentFenceStreaming = false;
      let _sfAgentFenceStreamedLen = 0;
      let _sfAgentFenceFilePath = '';
      let _sfHadAgentFenceRoute = false;
      let _sfFileRoutedChars = 0;

      const _sfEmitFileContentToken = (text) => {
        if (!text || !onStreamEvent) return;
        if (text.length) {
          _sfVisibleChars += text.length;
          _sfFileRoutedChars += text.length;
        }
        onStreamEvent('file-content-token', text);
      };

      const _sfResetAgentFenceStream = () => {
        _sfAgentFenceStreaming = false;
        _sfAgentFenceStreamedLen = 0;
        _sfAgentFenceFilePath = '';
      };

      const _sfResetContentEndForFile = (filePath) => {
        const np = _normalizePath(filePath);
        if (np) _sfContentEndCompleted.delete(np);
      };

      const _sfStartAgentCodeFenceStream = (filePath, fenceBuf) => {
        if (!filePath || !onStreamEvent) return;
        const np = _normalizePath(filePath);
        _sfResetContentEndForFile(filePath);
        const body = _sfExtractAgentFenceBody(fenceBuf);
        const fileName = filePath.split(/[\\/]/).pop() || filePath;
        const ext = fileName.includes('.') ? fileName.split('.').pop().toLowerCase() : '';
        if (!_sfAgentFenceStreaming || _sfAgentFenceFilePath !== filePath) {
          _trace('sf-content-start', { filePath, phase: 'agent-fence' });
          onStreamEvent('file-content-start', {
            filePath,
            fileName,
            language: ext,
            fileKey: np,
            op: 'write',
          });
          _sfStreamedFileWrites.add(np);
          _sfMarkFileContentStreamActive(filePath);
          _sfAgentFenceStreaming = true;
          _sfAgentFenceFilePath = filePath;
          _sfAgentFenceStreamedLen = 0;
          _sfHadAgentFenceRoute = true;
          const hm = fenceBuf.match(RE_FENCE_HEADER);
          if (hm) _sfVisibleChars += hm[0].length;
        }
        if (body.length > _sfAgentFenceStreamedLen) {
          const delta = body.slice(_sfAgentFenceStreamedLen);
          _sfAgentFenceStreamedLen = body.length;
          if (delta) {
            _trace('sf-content-token-emit', { filePath, textLen: delta.length, phase: 'agent-fence' });
            _sfEmitFileContentToken(delta);
          }
        }
      };

      const _sfEmitAgentFenceBodyDelta = (fenceBuf) => {
        if (!_sfAgentFenceStreaming || !_sfAgentFenceFilePath) return;
        const body = _sfExtractAgentFenceBody(fenceBuf);
        if (body.length > _sfAgentFenceStreamedLen) {
          const delta = body.slice(_sfAgentFenceStreamedLen);
          _sfAgentFenceStreamedLen = body.length;
          if (delta) {
            _sfEmitFileContentToken(delta);
          }
        }
      };

      const _sfFinalizeAgentCodeFenceStream = (fenceBuf = '') => {
        if (!_sfAgentFenceStreaming || !onStreamEvent) return;
        if (fenceBuf) {
          const hm = fenceBuf.match(RE_FENCE_HEADER);
          const body = _sfExtractAgentFenceBody(fenceBuf);
          const hdrLen = hm ? hm[0].length : 0;
          const wrapperTail = fenceBuf.length - hdrLen - body.length;
          if (wrapperTail > 0) _sfVisibleChars += wrapperTail;
        }
        const fileKey = _normalizePath(_sfAgentFenceFilePath);
        _trace('sf-content-end', { reason: 'agent-fence-close', filePath: _sfAgentFenceFilePath, sf: _traceSfState() });
        onStreamEvent('file-content-end', { filePath: _sfAgentFenceFilePath, fileKey });
        _sfContentEndCompleted.add(fileKey);
        _sfMarkFileContentStreamActive(null);
        _sfResetAgentFenceStream();
      };

      const _sfEmitReroutedThinkFile = (reroute) => {
        if (!reroute?.filePath || !onStreamEvent) return;
        if (!shouldStreamFileContentForAgent(options, reroute.filePath)) return;
        if (reroute.op === 'edit') {
          emitCompleteFileContentBlock(onStreamEvent, reroute.filePath, reroute.content, options, {
            op: 'edit',
            oldText: reroute.oldText || '',
            newText: reroute.content,
          });
        } else {
          emitCompleteFileContentBlock(onStreamEvent, reroute.filePath, reroute.content, options);
        }
      };

      const _traceSfState = () => ({
        active: _sfActive,
        confirmed: _sfConfirmed,
        inFence: _sfInFence,
        fileWriteDetected: _sfFileWriteDetected,
        contentStreamActive: _sfContentStreamActive,
        contentDone: _sfContentDone,
        contentEsc: _sfContentJsonState.escPending,
        unicodeCount: _sfContentJsonState.unicodeCount,
        quotePending: _sfContentJsonState.quotePending,
        depth: _sfDepth,
        inStr: _sfInStr,
        bufLen: _sfBuf.length,
        contentBufLen: _sfContentBuf.length,
        contentFilePath: _sfContentFilePath,
        fenceBufLen: _sfFenceBuf.length,
        visibleChars: _sfVisibleChars,
        nativeThinkActive: _sfNativeThinkActive,
        inThink: _sfInThink,
        fenceStreamPlain: _sfFenceStreamPlain,
      });
      const _traceSfChar = (ch) => {
        if (!_traceFull) return;
        streamTrace.trace('stream', 'sf-char', { ch, sf: _traceSfState() });
      };

      const _sfAbortPlainFenceStream = () => {
        _sfFenceStreamPlain = false;
        _sfFencePlainTick = 0;
        _sfFenceBuf = _sfFencePlainHeader + _sfFencePlainBody;
        _sfFencePlainHeader = '';
        _sfFencePlainBody = '';
      };

      const _sfResetPlainFenceStream = () => {
        _sfFenceStreamPlain = false;
        _sfFencePlainTick = 0;
        _sfFencePlainHeader = '';
        _sfFencePlainBody = '';
      };

      const _sfResetPerGenerationTurn = () => {
        _sfStreamedFileWrites.clear();
        _sfProsedFileWrites.clear();
        _sfContentEndCompleted.clear();
        _sfContentContinuation = null;
        _sfEarlyFileStartEmitted = false;
        _sfSwallowFenceDebris = false;
        _sfDebrisBuf = '';
        _sfResetAgentFenceStream();
        _sfHadAgentFenceRoute = false;
      };

      const _sfBulkReplayCtx = () => ({
        onStreamEvent,
        options,
        streamedSet: _sfStreamedFileWrites,
        normalizePath: _normalizePath,
        allowNewStart: _sfShouldAllowNewFileContentStart,
        endCompleted: _sfContentEndCompleted,
        markActive: _sfMarkFileContentStreamActive,
      });

      const _sfOnToolJsonFenceClose = (fenceBuf) => {
        if (!_sfFenceContentStreaming && !_sfEarlyFileStartEmitted) {
          _sfBulkReplayFileContentFromFence(fenceBuf, _sfBulkReplayCtx());
        }
        _sfSwallowFenceDebris = true;
        _sfDebrisBuf = '';
      };

      const _sfSaveContentContinuation = () => {
        if (!_sfContentFilePath) return;
        _sfContentContinuation = {
          filePath: _sfContentFilePath,
          streamIsEdit: _sfStreamIsEdit,
          oldText: _sfContentOldText,
        };
      };

      const _sfRestoreContentContinuationAfterReset = () => {
        const resume = _sfContentContinuation;
        if (!resume?.filePath) return;
        _sfContentFilePath = resume.filePath;
        _sfStreamIsEdit = !!resume.streamIsEdit;
        _sfContentOldText = resume.oldText || '';
        _sfFileWriteDetected = true;
        _sfContentStreamActive = true;
        _sfContentDone = false;
        _sfResetContentJsonState();
        _sfEarlyFileStartEmitted = true;
        _sfContentContinuation = null;
        this._fileContentStreamActivePath = resume.filePath;
        console.log(`[ChatEngine] Resuming file-content stream for ${resume.filePath}`);
      };

      const _sfShouldAllowNewFileContentStart = (filePath) => {
        if (_sfContentContinuation) return false;
        const np = _normalizePath(filePath);
        if (_sfContentEndCompleted.has(np)) {
          // Same-turn rewrite: allow reopen after prior stream session ended.
          _sfContentEndCompleted.delete(np);
        }
        return true;
      };

      const _sfMarkFileContentStreamActive = (filePath) => {
        this._fileContentStreamActivePath = filePath || null;
      };

      const _tryEarlyFileContentStart = (buf) => {
        const fileToolLikely = _sfFileWriteDetected
          || (RE_FILE_STREAM_TOOLS.test(buf) && RE_FILE_PATH.test(buf) && _sfIsToolLikeJson(buf));
        if (_sfEarlyFileStartEmitted || !fileToolLikely || _sfContentDone || !onStreamEvent) return;
        const partial = extractPartialWriteFileFromToolJson(buf);
        if (!partial?.filePath || !partial.content || partial.content.length === 0) return;
        const filePath = partial.filePath;
        if (!shouldStreamFileContentForAgent(options, filePath)) return;
        const np = _normalizePath(filePath);
        if (_sfStreamedFileWrites.has(np)) {
          if (_sfContentEndCompleted.has(np)) {
            _sfResetContentEndForFile(filePath);
          } else {
            return;
          }
        }
        if (!_sfShouldAllowNewFileContentStart(filePath)) return;
        _sfEarlyFileStartEmitted = true;
        _sfContentFilePath = filePath;
        _sfStreamIsEdit = !!partial.isEdit;
        if (_sfStreamIsEdit && !_sfContentOldText) {
          const oldM = buf.match(RE_OLD_TEXT_CAPTURE);
          if (oldM) _sfContentOldText = _jsonUnescape(oldM[1]);
        }
        const fileName = filePath.split(/[\\/]/).pop() || filePath;
        const ext = fileName.includes('.') ? fileName.split('.').pop().toLowerCase() : '';
        onStreamEvent('file-content-start', {
          filePath,
          fileName,
          language: ext,
          fileKey: np,
          op: _sfStreamIsEdit ? 'edit' : 'write',
          oldText: _sfContentOldText || undefined,
        });
        onStreamEvent('file-content-token', partial.content);
        _sfStreamedFileWrites.add(np);
        _sfMarkFileContentStreamActive(filePath);
      };

      const _sfEmitFenceContentDelta = (opts = {}) => {
        if (!_sfFileWriteDetected && !(RE_FILE_STREAM_TOOLS.test(_sfFenceBuf) && RE_FILE_PATH.test(_sfFenceBuf))) {
          return;
        }
        const partial = extractPartialWriteFileFromToolJson(_sfFenceBuf, {
          stripCompleteSuffix: true,
        });
        if (!partial?.filePath) return;
        const filePath = partial.filePath;
        const content = partial.content ?? '';
        if (!shouldStreamFileContentForAgent(options, filePath)) return;
        if (content.length === 0) return;
        const np = _normalizePath(filePath);
        if (!_sfFenceContentStreaming) {
          if (_sfStreamedFileWrites.has(np)) {
            if (_sfContentEndCompleted.has(np)) {
              _sfResetContentEndForFile(filePath);
              _sfFenceStreamedLen = 0;
            } else {
              return;
            }
          }
          if (!_sfShouldAllowNewFileContentStart(filePath)) return;
          _sfFenceContentStreaming = true;
          _sfContentFilePath = filePath;
          _sfStreamIsEdit = !!partial.isEdit;
          if (_sfStreamIsEdit && !_sfContentOldText) {
            const oldM = _sfFenceBuf.match(RE_OLD_TEXT_CAPTURE);
            if (oldM) _sfContentOldText = _jsonUnescape(oldM[1]);
          }
          const fileName = filePath.split(/[\\/]/).pop() || filePath;
          const ext = fileName.includes('.') ? fileName.split('.').pop().toLowerCase() : '';
          if (onStreamEvent) {
            _trace('sf-content-start', { filePath, phase: 'fence-delta' });
            onStreamEvent('file-content-start', {
              filePath,
              fileName,
              language: ext,
              fileKey: np,
              op: _sfStreamIsEdit ? 'edit' : 'write',
              oldText: _sfContentOldText || undefined,
            });
          }
          _sfStreamedFileWrites.add(np);
          _sfMarkFileContentStreamActive(filePath);
          _sfEarlyFileStartEmitted = true;
        }
        if (content.length > _sfFenceStreamedLen) {
          const delta = content.slice(_sfFenceStreamedLen);
          _sfFenceStreamedLen = content.length;
          if (onStreamEvent && delta) {
            _trace('sf-content-token-emit', { filePath, textLen: delta.length, phase: 'fence-delta' });
            onStreamEvent('file-content-token', delta);
          }
        }
      };

      const _sfFinalizeFenceContentStream = () => {
        if (!_sfFenceContentStreaming || !onStreamEvent) return;
        _sfEmitFenceContentDelta();
        const partial = extractPartialWriteFileFromToolJson(_sfFenceBuf, { stripCompleteSuffix: true });
        if (partial?.content != null) {
          const full = String(partial.content);
          if (full.length > _sfFenceStreamedLen) {
            onStreamEvent('file-content-token', full.slice(_sfFenceStreamedLen));
            _sfFenceStreamedLen = full.length;
          }
        }
        _trace('sf-content-end', { reason: 'fence-close', filePath: _sfContentFilePath, sf: _traceSfState() });
        onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _normalizePath(_sfContentFilePath) });
        _sfContentEndCompleted.add(_normalizePath(_sfContentFilePath));
        _sfMarkFileContentStreamActive(null);
        _sfFenceContentStreaming = false;
        _sfFenceStreamedLen = 0;
        _sfContentDone = true;
      };

      const _sfForward = (text) => {
        if (!text) return;
        if (isVisibleToolArtifact(text)) {
          console.log(`[ChatEngine] _sfForward: suppressed tool artifact (${text.length} chars)`);
          return;
        }
        _sfVisibleChars += text.length;
        if (_sfVisibleChars <= 30 || _sfVisibleChars % 1000 < text.length) {
          _logStreamDiag(`[StreamDiag] FORWARD: chars=${_sfVisibleChars} tail=${JSON.stringify(text.slice(-10))}`);
        }
        if (onToken) onToken(text);
      };

      const _sfFlush = () => {
        if (_sfContentStreamActive && onStreamEvent) {
          if (_sfContentBuf) {
            onStreamEvent('file-content-token', _sfContentBuf);
            _sfContentBuf = '';
          }
          onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _normalizePath(_sfContentFilePath) });
          _sfContentStreamActive = false;
        } else if (_sfBuf) {
          // Flush-guard: if the buffer contains tool-call JSON, discard it.
          // The toolParser will extract the call from the full response text post-generation.
          // This prevents raw JSON from appearing as visible text in the chat.
          const _isToolCall = _sfIsToolLikeJson(_sfBuf);
          if (_isToolCall) {
            console.log(`[ChatEngine] _sfFlush: discarding tool-call JSON (${_sfBuf.length} chars)`);
            const _fpM = _sfBuf.match(RE_FILE_PATH);
            if (_fpM && _fpM[1]) _sfProsedFileWrites.add(_normalizePath(_fpM[1]));
          } else {
            _sfForward(_sfBuf);
          }
        }
        _sfBuf = '';
        _sfDepth = 0;
        _sfActive = false;
        _sfConfirmed = false;
        _sfInStr = false;
        _sfEscaped = false;
        _sfFileWriteDetected = false;
        _sfToolCallNotified = false;
        _sfToolGeneratingStart = 0;
        _sfLastToolProgressAt = 0;
        _sfContentDone = false;
        _sfResetContentJsonState();
        _sfContentOldText = '';
        _sfStreamIsEdit = false;
        _sfEarlyFileStartEmitted = false;
        _sfThinkTagMatch = '';
        _sfInThink = false;     // ensure think-state never bleeds into the next generation
        _sfThinkBuf = '';
      };

      const _sfFlushFence = () => {
        if (_sfAgentFenceStreaming && onStreamEvent) {
          _sfEmitAgentFenceBodyDelta(_sfFenceBuf);
          _sfFinalizeAgentCodeFenceStream(_sfFenceBuf);
        } else if (_sfFenceContentStreaming && onStreamEvent) {
          _sfFinalizeFenceContentStream();
        } else if (_sfContentStreamActive && onStreamEvent) {
          if (_sfContentBuf) {
            onStreamEvent('file-content-token', _sfContentBuf);
            _sfContentBuf = '';
          }
          onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _normalizePath(_sfContentFilePath) });
          _sfContentStreamActive = false;
        }
        if (_sfFenceBuf) {
          const _isToolCall = _sfFenceBufferLooksLikeToolJson(_sfFenceBuf);
          if (_isToolCall) {
            console.log(`[ChatEngine] _sfFlushFence: discarding tool-call JSON (${_sfFenceBuf.length} chars)`);
            _sfOnToolJsonFenceClose(_sfFenceBuf);
            const _fpM = _sfFenceBuf.match(RE_FILE_PATH);
            if (_fpM && _fpM[1]) _sfProsedFileWrites.add(_normalizePath(_fpM[1]));
          } else {
            const payload = _sfPreparePlainFenceFlushPayload(_sfFenceBuf);
            if (payload.length > 0) _sfForward(payload);
          }
          _sfFenceBuf = '';
        }
        _sfInFence = false;
        _sfResetPlainFenceStream();
        _sfFenceTickCount = 0;
        _sfFileWriteDetected = false;
        _sfToolCallNotified = false;
        _sfContentDone = false;
        _sfResetContentJsonState();
        _sfInThink = false;     // ensure think-state never bleeds into the next generation
        _sfThinkBuf = '';
        _sfFenceInThink = false;
      };

      /** Forward any prose in fullResponse that never reached onToken during streaming. */
      const _sfCatchUpVisibleProse = () => {
        _sfFlush();
        _sfFlushFence();
        let cleanTarget = stripToolCallText(fullResponse);
        const fileRouted = _sfHadAgentFenceRoute || _sfFileRoutedChars > 0;
        if (fileRouted) {
          const before = cleanTarget.length;
          cleanTarget = _sfStripPlainCodeFencesFromProse(cleanTarget);
          if (cleanTarget.length < before) {
            console.log(`[ChatEngine] Prose catch-up: stripped ${before - cleanTarget.length} file-routed fence chars from prose target`);
          }
        }
        if (cleanTarget.length > _sfVisibleChars) {
          const delta = cleanTarget.slice(_sfVisibleChars);
          if (delta) {
            console.log(`[ChatEngine] Prose stream catch-up: ${_sfVisibleChars} → ${cleanTarget.length} visible chars (${delta.length} forwarded)`);
            _sfForward(delta);
          }
        } else if (fileRouted) {
          console.log(`[ChatEngine] Prose catch-up skipped — file-routed content already accounted (${cleanTarget.length} <= ${_sfVisibleChars})`);
        }
      };

      const _sfProcessChunk = (chunk) => {
        for (let i = 0; i < chunk.length; i++) {
          const ch = chunk[i];
          _traceSfChar(ch);

          if (_sfSwallowFenceDebris) {
            _sfDebrisBuf += ch;
            const t = _sfDebrisBuf;
            if (/^[\s`]*$/.test(t) && t.length <= 20) continue;
            if (/^`{3,}\s*$/.test(t.trim())) {
              _sfDebrisBuf = '';
              _sfSwallowFenceDebris = false;
              continue;
            }
            _sfSwallowFenceDebris = false;
            const debris = _sfDebrisBuf;
            _sfDebrisBuf = '';
            if (debris) _sfProcessChunk(debris);
            i--;
            continue;
          }

          if (_sfPendingFenceOpen) {
            _sfPendingFenceLine += ch;
            if (ch === '\n' || ch === '\r') {
              _sfPendingFenceOpen = false;
              const hdr = _sfPendingFenceLine.replace(/\r?\n$/, '');
              if (/^`{3,}[a-z0-9_-]*\s*$/i.test(hdr)) {
                _sfInFence = true;
                _sfFenceBuf = _sfPendingFenceLine;
                _sfResetPlainFenceStream();
              } else {
                _sfForward(_sfPendingFenceLine);
              }
              _sfPendingFenceLine = '';
              _sfLastCharWasNewlineOrStart = (ch === '\n' || ch === '\r');
              continue;
            }
            if (_sfPendingFenceLine.length > 12 && !/^`{3,}[a-z0-9_-]*$/i.test(_sfPendingFenceLine)) {
              _sfPendingFenceOpen = false;
              _sfForward(_sfPendingFenceLine);
              _sfPendingFenceLine = '';
              _sfLastCharWasNewlineOrStart = false;
              continue;
            }
            _sfLastCharWasNewlineOrStart = false;
            continue;
          }

          // Think-tag detection for reasoning models (non-Jinja only).
          // These models output thinking in raw text (LlamaCompletion mode).
          // We detect these tags and route thinking content to llm-thinking-token events
          // so it appears in thinking blocks instead of as regular prose.
          if (_sfRawThinkTagsEnabled && _sfInThink) {
            _sfThinkBuf += ch;
            // Tool payloads mis-routed into thinking (e.g. write_file HTML/JSON) — bail out to normal stream.
            if (_sfThinkBuf.length > 48) {
              const sample = _sfThinkBuf.slice(0, 4096);
              const looksLikeToolPayload = /"filePath"|"content"\s*:|className=|<\/\w+>|"tool"\s*:/.test(sample);
              if (looksLikeToolPayload) {
                console.log('[ChatEngine] thinking-mode force-exit — content looks like tool/file payload');
                const orphanThink = _sfThinkBuf;
                _sfInThink = false;
                _sfThinkBuf = '';
                if (onStreamEvent && !_thinkingFilterEnabled) {
                  onStreamEvent('llm-thinking-end', { position: _sfVisibleChars, length: 0, content: '' });
                }
                if (orphanThink) _sfProcessChunk(orphanThink);
                continue;
              }
            }
            // Plan A: thinking chars route ONLY to llm-thinking-token events.
            // The previous design dual-emitted to onToken (visible stream), which leaked the
            // </think> bytes as visible text byte-by-byte before the close-tag check fired.
            // Check for close tag </think> first.
            if (_sfThinkBuf.length >= 8 && _sfThinkBuf.endsWith('</think>')) {
              const thinkContent = _sfThinkBuf.slice(0, -8);
              const reroute = _sfRerouteThinkContentToFile(thinkContent, options, fullResponse);
              if (reroute) {
                _sfEmitReroutedThinkFile(reroute);
                console.log(`[ChatEngine] </think> closed — rerouted ${reroute.filePath} to file-content (${thinkContent.length} chars)`);
              } else if (thinkContent && onStreamEvent && !_thinkingFilterEnabled && !_sfNativeThinkActive) {
                _sfNativeThinkChars += thinkContent.length; // B03: count raw-text thinking
                onStreamEvent('llm-thinking-token', thinkContent);
                onStreamEvent('llm-thinking-end', {
                  position: _sfVisibleChars,
                  length: thinkContent.length,
                  content: thinkContent
                });
              }
              console.log(`[ChatEngine] </think> closed — thinking block: ${(thinkContent || '').length} chars${_sfNativeThinkActive ? ' (raw-text emit suppressed by B4 — native segment active)' : ''}${reroute ? ' (file reroute)' : ''}`);
              _sfInThink = false;
              _sfThinkBuf = '';
              continue;
            }
            // Plan I: detect code fence ``` inside think mode.
            // The model may be (a) emitting a tool call without closing think, OR
            // (b) demonstrating thinking tags as examples inside a code fence.
            // For (a): implicit close + route as tool call. For (b): keep thinking open.
            // We defer the decision until the fence closes and we can inspect its content.
            if (_sfThinkBuf.endsWith('\n```') || _sfThinkBuf === '```') {
              const fenceStart = _sfThinkBuf.lastIndexOf('```');
              const thinkBeforeFence = _sfThinkBuf.slice(0, fenceStart).replace(/\n$/, '');
              // Flush any thinking content before the fence
              if (thinkBeforeFence && onStreamEvent && !_thinkingFilterEnabled && !_sfNativeThinkActive) {
                _sfNativeThinkChars += thinkBeforeFence.length; // B03: count raw-text thinking
                onStreamEvent('llm-thinking-token', thinkBeforeFence);
              }
              console.log('[ChatEngine] code fence inside  thinking — deferring close decision until fence content is known');
              _sfFenceInThink = true;
              _sfThinkBuf = '';
              _sfInFence = true;
              _sfFenceBuf = '```';
              _sfResetPlainFenceStream();
              _sfFenceTickCount = 0;
              continue;
            }
            // Flush periodically to avoid unbounded buffer.
            // Preserve the last 7 chars (len('</think>')-1) so a close tag
            // that starts near the boundary is never split across two flushes.
            // Threshold lowered from 200 to 32 for responsive thinking-stream UI now that
            // thinking chars route exclusively through llm-thinking-token events.
            if (_sfThinkBuf.length > 32) {
              const CLOSE_TAG_TAIL = 7; // '</think>'.length - 1
              const toEmit = _sfThinkBuf.slice(0, -CLOSE_TAG_TAIL);
              const toKeep = _sfThinkBuf.slice(-CLOSE_TAG_TAIL);
              // B4: Suppress raw-text emit if native segment path already handled this content.
              if (toEmit && onStreamEvent && !_thinkingFilterEnabled && !_sfNativeThinkActive) {
                _sfNativeThinkChars += toEmit.length; // B03: count raw-text thinking
                onStreamEvent('llm-thinking-token', toEmit);
              }
              _sfThinkBuf = toKeep;
            }
            continue;
          }

          // Check for <think> open or </think> close tag — buffer chars so the tag itself isn't forwarded to UI.
          // Plan A: matching </think> in normal mode silently consumes orphan close tags so they don't leak
          // to the visible chat stream when the model emits </think> without a preceding <think>.
          // Skip think-tag matching during file-write fences so </html> etc. are not buffered/consumed.
          if (!_sfContentStreamActive && !(_sfInFence && (_sfFileWriteDetected || _sfToolCallNotified))
            && _sfRawThinkTagsEnabled && (_sfThinkTagMatch.length > 0 || ch === '<')) {
            _sfThinkTagMatch += ch;
            const OPEN_TAG = '<think>';
            const CLOSE_TAG = '</think>';
            if (_sfThinkTagMatch === OPEN_TAG) {
              _sfThinkTagMatch = '';
              if (_sfNativeThinkActive) {
                console.log('[ChatEngine] <think> open tag consumed (native segments active — tag stripped)');
                continue;
              }
              // Suppress think-tag detection inside streamed file content.
              // File content inside a write_file JSON string is opaque; any <think> tags here are artifacts
              // and must not flip routing to the thinking channel mid-file.
              if (_sfContentStreamActive) {
                console.log('[ChatEngine] thinking-tag in content stream - suppressed (opaque file content)');
                continue;
              }
              if (_sfInFence || _sfFileWriteDetected || _sfToolCallNotified) {
                console.log('[ChatEngine] thinking-tag suppressed (tool generation active)');
                _sfThinkTagMatch = '';
                continue;
              }
              // Full open match — enter thinking mode, discard the tag
              _sfInThink = true;
              _sfThinkBuf = '';
              if (onStreamEvent && !_thinkingFilterEnabled) {
                onStreamEvent('llm-thinking-start', { position: _sfVisibleChars });
              }
              console.log('[ChatEngine] <think> tag detected — routing to llm-thinking-token (raw text path)');
              continue;
            } else if (_sfThinkTagMatch === CLOSE_TAG) {
              _sfThinkTagMatch = '';
              if (_sfNativeThinkActive) {
                console.log('[ChatEngine] orphan </think> consumed (native segments active — tag stripped)');
                continue;
              }
              // Orphan </think> — tag was preceded by no <think> open in stream.
              // Silently consume. Mode C injects <think> as prefix before generation;
              // if the model emits </think> without a matching open visible in the stream,
              // this is expected (the open was injected, not streamed). Do not move chat text.
              console.log('[ChatEngine] orphan </think> consumed (no retroactive move)');
              continue;
            } else if (!OPEN_TAG.startsWith(_sfThinkTagMatch) && !CLOSE_TAG.startsWith(_sfThinkTagMatch)) {
              // Not matching either tag — flush buffered chars to normal processing
              const flush = _sfThinkTagMatch.slice(0, -1);
              _sfThinkTagMatch = '';
              // Re-process flushed chars + current char through normal filter path
              if (flush) _sfProcessChunk(flush);
              // fall through with current ch below
            } else {
              // Partial match for one or both tags — keep buffering
              continue;
            }
          }

          // ── Fence mode: accumulating content inside ```...``` ──
          if (_sfInFence) {
            if (_sfAgentFenceStreaming) {
              _sfFenceBuf += ch;
              if (_sfFenceCloseTickBlocked()) {
                _sfFenceTickCount = 0;
              } else if (ch === '`') {
                _sfFenceTickCount++;
              } else {
                _sfFenceTickCount = 0;
              }
              if (_sfFenceTickCount >= 3) {
                _sfEmitAgentFenceBodyDelta(_sfFenceBuf);
                _sfFinalizeAgentCodeFenceStream(_sfFenceBuf);
                _sfFenceBuf = '';
                _sfInFence = false;
                _sfFenceTickCount = 0;
                _sfLastCharWasNewlineOrStart = true;
                continue;
              }
              _sfEmitAgentFenceBodyDelta(_sfFenceBuf);
              continue;
            }

            // Stream normal markdown code fences (```html, ```css, …) to the UI immediately.
            // Only JSON tool-call fences stay buffered until close (so we can strip/suppress).
            if (_sfFenceStreamPlain) {
              let abortToBuffer = false;
              if (ch === '`') {
                _sfFencePlainTick++;
                if (_sfFencePlainTick >= 3) {
                  _sfForward('```');
                  _sfInFence = false;
                  _sfResetPlainFenceStream();
                  _sfFenceBuf = '';
                  _sfLastCharWasNewlineOrStart = true;
                }
              } else {
                if (_sfFencePlainTick > 0) {
                  const ticks = '`'.repeat(_sfFencePlainTick);
                  _sfForward(ticks);
                  _sfFencePlainBody += ticks;
                  _sfFencePlainTick = 0;
                }
                _sfFencePlainBody += ch;
                if (_sfFencePlainBody.length <= 200
                  && (_sfIsToolLikeJson(_sfFencePlainBody) || /"tool"\s*:\s*"/.test(_sfFencePlainBody))) {
                  _sfAbortPlainFenceStream();
                  abortToBuffer = true;
                } else {
                  _sfForward(ch);
                }
              }
              if (!abortToBuffer) continue;
            }

            _sfFenceBuf += ch;

            if (!_sfFenceStreamPlain && !_sfFileWriteDetected && !_sfContentStreamActive && RE_FENCE_HEADER.test(_sfFenceBuf)) {
              if (_sfFenceHeaderShouldStreamPlain(_sfFenceBuf)) {
                if (_sfShouldRouteAgentCodeFence(_sfFenceBuf, options)) {
                  const agentPath = _sfInferAgentFenceFilePath(_sfFenceBuf, fullResponse);
                  if (agentPath && shouldStreamFileContentForAgent(options, agentPath)) {
                    _sfStartAgentCodeFenceStream(agentPath, _sfFenceBuf);
                    continue;
                  }
                }
                const hm = _sfFenceBuf.match(RE_FENCE_HEADER);
                _sfFencePlainHeader = hm ? _sfFenceBuf.slice(0, hm.index + hm[0].length) : '';
                _sfFencePlainBody = hm ? _sfFenceBuf.slice(hm.index + hm[0].length) : _sfFenceBuf;
                _sfFenceStreamPlain = true;
                _sfForward(_sfFenceBuf);
                _sfFenceBuf = '';
                continue;
              }
              // Tool-fence languages (json/tool/…) or tool-shaped body — keep buffering until close.
            }

            // Real-time content streaming from WITHIN a fenced tool call (fence-buffer delta).
            if (_sfFileWriteDetected || (RE_FILE_STREAM_TOOLS.test(_sfFenceBuf) && RE_FILE_PATH.test(_sfFenceBuf))) {
              _sfEmitFenceContentDelta();
            }
            // Emit tool-generating for ANY tool call inside a fence (not just file-write)
            if (!_sfToolCallNotified && _sfFenceBuf.length > 30) {
              if (_sfIsToolLikeJson(_sfFenceBuf)) {
                _sfToolCallNotified = true;
                _sfToolGeneratingStart = Date.now();
                _sfLastToolProgressAt = _sfToolGeneratingStart;
                if (onStreamEvent) {
                  onStreamEvent('tool-generating', { tool: _sfExtractGeneratingToolName(_sfFenceBuf) });
                }
              }
            }
            if (_sfToolCallNotified && onStreamEvent && _sfFenceBuf.length > 0) {
              const _progressNow = Date.now();
              if (_progressNow - _sfLastToolProgressAt >= 5000) {
                _sfLastToolProgressAt = _progressNow;
                const _fpProg = _sfFenceBuf.match(RE_FILE_PATH);
                onStreamEvent('tool-generating-progress', {
                  tool: _sfExtractGeneratingToolName(_sfFenceBuf),
                  elapsedMs: _progressNow - _sfToolGeneratingStart,
                  fenceChars: _sfFenceBuf.length,
                  filePath: _fpProg ? _jsonUnescape(_fpProg[1]) : undefined,
                });
              }
            }
            // File-write detection is separate — only for content streaming
            if (!_sfFileWriteDetected && _sfFenceBuf.length > 30) {
              if (RE_FILE_STREAM_TOOLS.test(_sfFenceBuf) && _sfIsToolLikeJson(_sfFenceBuf)) {
                _sfFileWriteDetected = true;
                _sfStreamIsEdit = RE_FILE_EDIT_TOOLS.test(_sfFenceBuf);
              }
            }

            // Detect closing ``` — but NOT while char-FSM is mid-escape inside JSON string
            if (_sfFenceCloseTickBlocked()) {
              _sfFenceTickCount = 0;
            } else if (ch === '`') {
              _sfFenceTickCount++;
            } else {
              _sfFenceTickCount = 0;
            }

            if (_sfFenceTickCount >= 3) {
              // Closing fence found — flush any pending content
              if (_sfFenceContentStreaming) {
                _sfFinalizeFenceContentStream();
              } else if (_sfContentStreamActive && onStreamEvent) {
                if (_sfContentBuf) {
                  onStreamEvent('file-content-token', _sfContentBuf);
                  _sfContentBuf = '';
                }
                onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _normalizePath(_sfContentFilePath) });
                _sfContentStreamActive = false;
              }
              // Fix 4: If this fence opened inside a thinking block, decide based on content.
              if (_sfFenceInThink) {
                _sfFenceInThink = false;
                const isToolFence = _sfIsToolLikeJson(_sfFenceBuf);
                if (isToolFence) {
                  // Case (a): tool call inside think — implicit close, route as tool call
                  console.log('[ChatEngine] fence-in-think: tool call detected — implicit think close');
                  if (_sfThinkBuf && onStreamEvent && !_thinkingFilterEnabled && !_sfNativeThinkActive) {
                    _sfNativeThinkChars += _sfThinkBuf.length; // B03: count raw-text thinking
                    onStreamEvent('llm-thinking-token', _sfThinkBuf);
                    onStreamEvent('llm-thinking-end', { position: _sfVisibleChars, length: _sfThinkBuf.length, content: _sfThinkBuf });
                  }
                  _sfInThink = false;
                  _sfThinkBuf = '';
                  _sfFenceBuf = '';
                } else {
                  const reroute = _sfRerouteThinkContentToFile(_sfFenceBuf, options, fullResponse);
                  if (reroute) {
                    console.log('[ChatEngine] fence-in-think: file fence — rerouting to file-content');
                    _sfEmitReroutedThinkFile(reroute);
                    _sfFenceBuf = '';
                  } else {
                    // Case (b): prose fence inside think — emit as thinking content, stay in think
                    console.log('[ChatEngine] fence-in-think: non-tool fence — emitting as thinking content');
                    if (onStreamEvent && !_thinkingFilterEnabled && !_sfNativeThinkActive) {
                      _sfNativeThinkChars += _sfFenceBuf.length; // B03: count raw-text thinking
                      onStreamEvent('llm-thinking-token', _sfFenceBuf);
                    }
                    _sfFenceBuf = '';
                  }
                  // Stay in think mode — _sfInThink remains true
                }
              } else {
                // Normal fence close (not inside think)
                if (_sfIsToolLikeJson(_sfFenceBuf)) {
                  _sfOnToolJsonFenceClose(_sfFenceBuf);
                  _sfFenceBuf = '';
                } else {
                  _sfFlushFence();
                }
              }
              _sfInFence = false;
              _sfFileWriteDetected = false;
              _sfToolCallNotified = false;
              _sfToolGeneratingStart = 0;
              _sfLastToolProgressAt = 0;
              _sfContentDone = false;
              _sfFenceContentStreaming = false;
              _sfFenceStreamedLen = 0;
              _sfResetContentJsonState();
              _sfLastCharWasNewlineOrStart = true;
              continue;
            }
            continue;
          }

          // ── Normal mode ──
          if (!_sfActive) {

            // Detect opening ``` at line start
            if (ch === '`' && _sfLastCharWasNewlineOrStart) {
              _sfFenceTickCount++;
              if (_sfFenceTickCount >= 3) {
                _sfPendingFenceOpen = true;
                _sfPendingFenceLine = '```';
                _sfFenceTickCount = 0;
                _sfLastCharWasNewlineOrStart = false;
                continue;
              }
              continue;
            }
            // If we had 1-2 backticks but not 3, flush them
            if (_sfFenceTickCount > 0 && ch !== '`') {
              _sfForward('`'.repeat(_sfFenceTickCount));
              _sfFenceTickCount = 0;
            }

            // Look for `{` at line start (or after only whitespace on the line)
            if (ch === '{' && _sfLastCharWasNewlineOrStart) {
              _sfActive = true;
              _sfBuf = '{';
              _sfDepth = 1;
              _sfConfirmed = false;
              _sfInStr = false;
              _sfEscaped = false;
              _sfLastCharWasNewlineOrStart = false;
              continue;
            }
            _sfLastCharWasNewlineOrStart = (ch === '\n' || ch === '\r');
            if (ch === ' ' || ch === '\t') { /* keep the flag */ }
            else if (ch !== '\n' && ch !== '\r') _sfLastCharWasNewlineOrStart = false;
            _sfForward(ch);
            continue;
          }

          // ── Inside a potential raw JSON tool call ──
          _sfBuf += ch;

          // ── Real-time file content streaming ──
          if (_sfContentStreamActive) {
            _sfProcessContentStreamChar(ch, 'json-stream');
          } else if (_sfConfirmed && _sfFileWriteDetected && !_sfContentDone) {
            const _startRe = _sfStreamIsEdit ? RE_NEW_TEXT_START : RE_CONTENT_START;
            if (ch === '"' && _startRe.test(_sfBuf)) {
              const fpMatch = _sfBuf.match(RE_FILE_PATH);
              _sfContentFilePath = fpMatch ? fpMatch[1] : '';
              if (_sfStreamIsEdit) {
                const oldM = _sfBuf.match(RE_OLD_TEXT_CAPTURE);
                if (oldM) _sfContentOldText = _jsonUnescape(oldM[1]);
              }
              if (shouldStreamFileContentForAgent(options, _sfContentFilePath)
                && _sfShouldAllowNewFileContentStart(_sfContentFilePath)) {
                _sfContentStreamActive = true;
                _sfResetContentJsonState();
                const fileName = _sfContentFilePath.split(/[\\/]/).pop() || _sfContentFilePath;
                const ext = fileName.includes('.') ? fileName.split('.').pop().toLowerCase() : '';
                if (onStreamEvent) {
                  onStreamEvent('file-content-start', {
                    filePath: _sfContentFilePath,
                    fileName,
                    language: ext,
                    fileKey: _normalizePath(_sfContentFilePath),
                    op: _sfStreamIsEdit ? 'edit' : 'write',
                    oldText: _sfContentOldText || undefined,
                  });
                }
                _sfStreamedFileWrites.add(_normalizePath(_sfContentFilePath));
                _sfMarkFileContentStreamActive(_sfContentFilePath);
              } else {
                _sfContentDone = true;
              }
            }
          }
          if (_sfConfirmed && !_sfFileWriteDetected && _sfBuf.length > 15) {
            if (RE_FILE_STREAM_TOOLS.test(_sfBuf)) {
              _sfFileWriteDetected = true;
              _sfStreamIsEdit = RE_FILE_EDIT_TOOLS.test(_sfBuf);
            }
          }
          if (_sfFileWriteDetected && !_sfContentDone) {
            _tryEarlyFileContentStart(_sfBuf);
          }

          if (_sfEscaped) { _sfEscaped = false; continue; }
          if (ch === '\\' && _sfInStr) { _sfEscaped = true; continue; }
          if (ch === '"') { _sfInStr = !_sfInStr; continue; }
          if (_sfInStr) continue;

          if (ch === '{') _sfDepth++;
          else if (ch === '}') _sfDepth--;

          if (!_sfConfirmed && _sfBuf.length <= 80) {
            if (_sfIsToolLikeJson(_sfBuf)) {
              _sfConfirmed = true;
              _sfToolGeneratingStart = Date.now();
              _sfLastToolProgressAt = _sfToolGeneratingStart;
              if (onStreamEvent) {
                onStreamEvent('tool-generating', { tool: _sfExtractGeneratingToolName(_sfBuf) });
              }
            }
          }

          if (!_sfConfirmed && _sfBuf.length > 80) {
            _sfFlush();
            _sfLastCharWasNewlineOrStart = false;
            continue;
          }

          if (_sfDepth === 0) {
            if (_sfConfirmed) {
              if (_sfContentBuf && _sfContentStreamActive && onStreamEvent) {
                onStreamEvent('file-content-token', _sfContentBuf);
                _sfContentBuf = '';
              }
              _sfBuf = '';
            } else {
              // Unconfirmed buffer reached depth 0 — flush as normal prose
              _sfFlush();
            }
            _sfActive = false;
            _sfConfirmed = false;
            _sfFileWriteDetected = false;
            _sfContentDone = false;
            _sfLastCharWasNewlineOrStart = false;
          }
        }
      };

      // Build common generation options
      // S5: reasoningEffort maps to thinkingBudget when thinkingBudget is 0 (auto)
      // Fix 7: Respect profile thinkTokens mode — 'none' disables thinking, 'budget' provides default
      const profileThinkMode = this._modelProfile?.thinkTokens?.mode;
      const profileThinkBudget = this._modelProfile?.thinkTokens?.budget;
      let thinkBudget = options.thinkingBudget;
      const reasoningEffort = options.reasoningEffort;
      // No thought budget on models that don't support thinking (template + profile gate at load)
      if (!this._thinkingCapable || profileThinkMode === 'none') {
        thinkBudget = 0;
      } else if (thinkBudget == null) {
        thinkBudget = 0;
      } else if (thinkBudget === 0) {
        // Explicit auto — do not override with profile budget
      } else if (!thinkBudget && profileThinkMode === 'budget' && profileThinkBudget) {
        thinkBudget = profileThinkBudget;
      }
      if ((!thinkBudget || thinkBudget === 0) && reasoningEffort && profileThinkMode !== 'none') {
        if (reasoningEffort === 'low') thinkBudget = 512;
        else if (reasoningEffort === 'medium') thinkBudget = 2048;
        else if (reasoningEffort === 'high') thinkBudget = 8192;
      }
      const _thinkingActive = thinkBudget > 0 && profileThinkMode !== 'none';
      const _agentToolLoop = _toolsEnabled && !options.askOnly;
      const _samplingProfile = resolveSamplingProfile(this._modelProfile, {
        agentToolLoop: _agentToolLoop,
        thinkingActive: _thinkingActive,
      });
      const genOptions = {
        signal: this._abortController.signal,
        stopOnAbortSignal: true,
        temperature: (options.temperature != null && !options.temperatureIsDefault)
          ? options.temperature
          : (_samplingProfile?.temperature ?? options.temperature ?? 0.4),
        topP: options.topP ?? _samplingProfile?.topP,
        topK: options.topK ?? _samplingProfile?.topK,
        repeatPenalty: {
          penalty: (options.repeatPenalty != null && !options.repeatPenaltyIsDefault)
            ? options.repeatPenalty
            : (_samplingProfile?.repeatPenalty ?? options.repeatPenalty ?? 1.1),
          frequencyPenalty: options.frequencyPenalty ?? _samplingProfile?.frequencyPenalty ?? 0,
          presencePenalty: options.presencePenalty ?? _samplingProfile?.presencePenalty ?? 0,
          lastTokens: _samplingProfile?.lastTokensPenaltyCount ?? 128,
        },
        dryRepeatPenalty: resolveAgentDryRepeatPenalty(_agentToolLoop),
        seed: options.seed ?? undefined,
        contextShift: { strategy: this._contextShiftStrategy.bind(this) },
        onTextChunk: (chunk) => {
          if (!chunk) return;
          _trace('token-prose', { text: chunk });
          _proseLogBuf += chunk;
          if (_proseLogBuf.includes('\n')) {
            _logStreamDiag(`[StreamDiag] PROSE: ${JSON.stringify(_proseLogBuf)}`);
            _proseLogBuf = '';
          }
          fullResponse += chunk;
          _sfProcessChunk(chunk);
          tokensSinceLastUsageReport++;
          genTokenCount++;
          totalGenTokens++;
          if (onContextUsage && tokensSinceLastUsageReport >= 50) {
            tokensSinceLastUsageReport = 0;
            onContextUsage({
              used: this._sequence.nextTokenIndex,
              total: this._context.contextSize,
            });
          }
        },
        onResponseChunk: (chunk) => {
          if (_thinkingFilterEnabled) return;
          const text = chunk.text || '';
          if (!text && chunk.type !== 'segment') return;
          if (text) {
            _trace('token-response-chunk', {
              text,
              type: chunk.type,
              segmentType: chunk.segmentType,
              segmentStart: chunk.segmentStartTime,
              segmentEnd: chunk.segmentEndTime,
            });
          }

          if (text && chunk.type === 'segment' && chunk.segmentType === 'thought') {
            _thinkLogBuf += text;
            if (_thinkLogBuf.includes('\n')) {
              _logStreamDiag(`[StreamDiag] THINK: ${JSON.stringify(_thinkLogBuf)}`);
              _thinkLogBuf = '';
            }
          }

          // Native thought segments → thinking dropdown only (never visible chat / onToken)
          if (chunk.type === 'segment' && chunk.segmentType === 'thought') {
            _sfNativeThinkActive = true;
            _sfNativeThinkChars += text.length;
            nativeThinkFullText += text;
            if (onContextUsage && this._sequence) {
              onContextUsage({ used: this._sequence.nextTokenIndex, total: this._context.contextSize });
            }
            totalGenTokens += chunk.tokens?.length || 1;
            if (chunk.segmentStartTime && onStreamEvent) {
              onStreamEvent('llm-thinking-start', { position: _sfVisibleChars });
            }
            if (text && onStreamEvent) onStreamEvent('llm-thinking-token', text);
            if (chunk.segmentEndTime && onStreamEvent) {
              onStreamEvent('llm-thinking-end', { position: _sfVisibleChars, length: 0, content: '' });
            }
            if (!this._nativeThinkLogged) {
              this._nativeThinkLogged = true;
              console.log('[ChatEngine] Native thought segments active for this generation');
            }
            return;
          }

          // Visible main text: onTextChunk + _sfProcessChunk only (no _sfForward here — avoids 2× buffer/UI)
          if (chunk.type === 'segment' && chunk.segmentType !== 'thought') {
            fullResponse += text;
            _sfProcessChunk(text);
          }
        },
      };
      this._nativeThinkLogged = false; // reset per generation

      // Thinking budget: -1 = unlimited, 0 = auto (node-llama-cpp default), >0 = exact cap
      if (thinkBudget != null && thinkBudget !== 0) {
        genOptions.budgets = {
          thoughtTokens: thinkBudget === -1 ? Infinity : thinkBudget,
        };
        console.log(`[ChatEngine] Thinking budget: ${thinkBudget === -1 ? 'unlimited' : thinkBudget + ' tokens'}`);
      } else {
        console.log('[ChatEngine] Thinking budget: 0 (auto) — native thinking NOT explicitly enabled');
      }

      // Grammar-constrained generation: when enableGrammar is true, use
      // node-llama-cpp's LlamaJsonSchemaGrammar to force valid JSON tool calls.
      // Disabled by default — small models may loop or hang with grammar constraints.
      // User has total control via settings toggle.
      // NOTE: grammar and native functions are mutually exclusive (LlamaChat.d.ts:317-324).
      //       Native functions take precedence when both are requested.
      if (options.enableGrammar && functions && Object.keys(functions).length > 0) {
        try {
          const llamaCppPath = this._getNodeLlamaCppPath();
          const { LlamaJsonSchemaGrammar } = await import(pathToFileURL(llamaCppPath).href);
          const schema = {
            type: 'object',
            properties: {
              tool: { type: 'string', enum: Object.keys(functions) },
              params: { type: 'object' },
            },
            required: ['tool', 'params'],
          };
          genOptions.grammar = new LlamaJsonSchemaGrammar(this._llama, schema);
          console.log('[ChatEngine] Grammar-constrained generation enabled — tool calls forced to valid JSON schema');
        } catch (grammarErr) {
          console.warn(`[ChatEngine] Grammar setup failed (node-llama-cpp may not support it): ${grammarErr.message}`);
        }
      }

      // Native function calling: pass functions to LlamaChat so the wrapper uses grammar-constrained
      // function call tokens instead of prose JSON. Falls back to prose parse if stopReason !== 'functionCalls'.
      // Mutually exclusive with grammar — skip when grammar is already set.
      // Mode C (ThinkingOpenJinja + noPrefixTrigger) + native FC traps the entire reply in the
      // thought segment with visibleLen=0 — log-proven on GLM-4.6V-Flash. Tools still work via prose
      // tool prompt + parseToolCalls; only node-llama-cpp native FC tokens are disabled.
      const _modeCWrapper = this._currentThinkingMode === 'C';
      const _useNativeFunctions = !!(
        functions && Object.keys(functions).length > 0 &&
        !options.askOnly &&
        _toolsEnabled &&
        !_modeCWrapper &&
        !genOptions.grammar &&
        options.enableNativeFC !== false
      );
      if (_useNativeFunctions) {
        genOptions.functions = functions;
        genOptions.documentFunctionParams = true;
        this._shiftMeasureFunctions = functions;
        this._shiftMeasureDocumentFunctionParams = true;
        const _fcStreams = new Map();
        let _fcUsageChunks = 0;
        genOptions.onFunctionCallParamsChunk = (chunk) => {
          const { callIndex, functionName, paramsChunk, done } = chunk;

          // ── Throttled context ring update during FC generation ──────────────
          totalGenTokens++;
          _fcUsageChunks++;
          if (onContextUsage && this._sequence && _fcUsageChunks >= 50) {
            _fcUsageChunks = 0;
            onContextUsage({ used: this._sequence.nextTokenIndex, total: this._context.contextSize });
          }

          // ── Per-call state ───────────────────────────────────────────────────
          if (!_fcStreams.has(callIndex)) {
            _fcStreams.set(callIndex, {
              logBuf: '', buf: '', phase: 0, chunkCount: 0,
              filePath: '', fileName: '', ext: '',
              jsonState: _createJsonStringStreamState(),
              startEmitted: false, oldText: '',
            });
            // File stream ops use FileContentBlock / FileDiffBlock — others get tool-generating card
            const _FC_FILE_STREAM_OPS = new Set(['write_file', 'create_file', 'append_to_file', 'edit_file', 'replace_in_file']);
            if (!_FC_FILE_STREAM_OPS.has(functionName) && onStreamEvent) {
              onStreamEvent('tool-generating', { tool: functionName });
            }
          }
          const s = _fcStreams.get(callIndex);
          s.chunkCount++;

          // ── Comprehensive FC logging: every token accounted for ──────────────
          // First chunk: log immediately so we see function name + JSON start
          // Every 100 chunks: log progress (cumulative byte count + last 100 chars)
          // Done: log full params (capped at 600 chars with head+tail)
          // Never skips a token — chunkCount proves every chunk arrived
          s.logBuf += paramsChunk;
          if (_traceOn) {
            streamTrace.trace('stream', 'fc-chunk', {
              functionName,
              callIndex,
              paramsChunk,
              done,
              chunkCount: s.chunkCount,
              logBuf: s.logBuf,
            });
          }
          if (s.chunkCount === 1) {
            _logStreamDiag(`[StreamDiag] FC ${functionName}[${callIndex}] START chunk#1: "${s.logBuf.slice(0, 120)}"`);
          } else if (s.chunkCount % 100 === 0) {
            _logStreamDiag(`[StreamDiag] FC ${functionName}[${callIndex}] @chunk=${s.chunkCount} bytes=${s.logBuf.length} last100="${s.logBuf.slice(-100)}"`);
          }
          if (done) {
            const total = s.logBuf.length;
            const preview = total > 600 ? `${s.logBuf.slice(0, 300)} ... ${s.logBuf.slice(-300)}` : s.logBuf;
            _logStreamDiag(`[StreamDiag] FC ${functionName}[${callIndex}] DONE chunks=${s.chunkCount} bytes=${total}: "${preview}"`);
          }

          // ── write_file / edit_file content streaming → file-content-start/token/end ─────
          const _FC_FILE_STREAM_OPS = new Set(['write_file', 'create_file', 'append_to_file', 'edit_file', 'replace_in_file']);
          if (!_FC_FILE_STREAM_OPS.has(functionName) || s.phase === 2) return;
          if (s.isEdit == null) {
            s.isEdit = functionName === 'edit_file' || functionName === 'replace_in_file';
          }

          if (s.phase === 0) {
            s.buf += paramsChunk;

            if (!s.filePath) {
              const fpM = s.buf.match(/"filePath"\s*:\s*"((?:[^"\\]|\\.)*)"/);
              if (fpM) {
                s.filePath = _jsonUnescape(fpM[1]);
                s.fileName = s.filePath.split(/[\\/]/).pop() || s.filePath;
                s.ext = s.fileName.includes('.') ? s.fileName.split('.').pop().toLowerCase() : '';
              }
            }

            if (s.isEdit && !s.oldText) {
              const oldM = s.buf.match(/"oldText"\s*:\s*"((?:[^"\\]|\\.)*)"/);
              if (oldM) s.oldText = _jsonUnescape(oldM[1]);
            }

            if (s.filePath && !s.startEmitted) {
              if (!shouldStreamFileContentForAgent(options, s.filePath)) {
                s.phase = 2;
                return;
              }
              s.startEmitted = true;
              if (onStreamEvent) {
                onStreamEvent('file-content-start', {
                  filePath: s.filePath,
                  fileName: s.fileName,
                  language: s.ext,
                  fileKey: s.filePath,
                  op: s.isEdit ? 'edit' : 'write',
                  oldText: s.oldText || undefined,
                });
              }
            }

            const contentRe = s.isEdit ? /"newText"\s*:\s*"([\s\S]*)/ : /"content"\s*:\s*"([\s\S]*)/;
            const contentMatch = s.buf.match(contentRe);
            if (contentMatch && s.filePath) {
              if (!shouldStreamFileContentForAgent(options, s.filePath)) {
                s.phase = 2;
                return;
              }
              s.phase = 1;
              s.buf = '';
              if (!s.startEmitted && onStreamEvent) {
                onStreamEvent('file-content-start', {
                  filePath: s.filePath,
                  fileName: s.fileName,
                  language: s.ext,
                  fileKey: s.filePath,
                  op: s.isEdit ? 'edit' : 'write',
                  oldText: s.oldText || undefined,
                });
                s.startEmitted = true;
              }
              const after = contentMatch[1];
              if (after) {
                const { out, state, ended } = _jsonStringChunkDecode(after, s.jsonState);
                s.jsonState = state;
                if (out && onStreamEvent) onStreamEvent('file-content-token', out);
                if (ended) {
                  if (onStreamEvent) onStreamEvent('file-content-end', { filePath: s.filePath, fileKey: s.filePath });
                  s.phase = 2;
                  return;
                }
              }
            }

            if (done && s.phase === 1 && onStreamEvent) {
              onStreamEvent('file-content-end', { filePath: s.filePath, fileKey: s.filePath });
              s.phase = 2;
            }
          } else if (s.phase === 1) {
            const { out, state, ended } = _jsonStringChunkDecode(paramsChunk, s.jsonState);
            s.jsonState = state;
            if (out && onStreamEvent) onStreamEvent('file-content-token', out);
            if (ended || done) {
              if (onStreamEvent) onStreamEvent('file-content-end', { filePath: s.filePath, fileKey: s.filePath });
              s.phase = 2;
            }
          }
        };
        console.log(`[ChatEngine] Native function calling active: ${Object.keys(functions).length} tools`);
      } else {
        this._shiftMeasureFunctions = undefined;
        this._shiftMeasureDocumentFunctionParams = undefined;
      }
      if (!_useNativeFunctions && _modeCWrapper && functions && Object.keys(functions).length > 0 && _toolsEnabled && !options.askOnly) {
        console.log(`[ChatEngine] Mode C: native FC disabled (${Object.keys(functions).length} tools via prose prompt only — avoids thought-segment trap)`);
      }

      // Add lastEvaluation context window if available
      if (this._lastEvaluation) {
        genOptions.lastEvaluationContextWindow = {
          contextWindow: this._lastEvaluation.contextWindow,
          contextShiftMetadata: this._lastEvaluation.contextShiftMetadata,
        };
      }

      // ─── Generation context size ───
      const contextSize = this._context.contextSize;
      const usedTokens = this._sequence.nextTokenIndex;
      const availableForGeneration = contextSize - usedTokens;

      // Only honor an explicit user-provided maxTokens cap.
      // Default: no cap — the library's contextShiftSize handles rotation transparently.
      const userCap = (options.maxTokens > 0) ? options.maxTokens : Infinity;
      const userMaxTokens = userCap;
      if (userCap !== Infinity) {
        genOptions.maxTokens = Math.min(userCap, availableForGeneration);
      }
      // Log generation setup for diagnostics
      console.log(`[ChatEngine] Generation setup: maxTokens=${genOptions.maxTokens || '(unlimited)'}, contextSize=${contextSize}, usedTokens=${usedTokens}, available=${availableForGeneration}, chatHistory=${this._chatHistory.length} msgs, temperature=${genOptions.temperature}`);

      // Generate response — model outputs text which may contain tool call JSON blocks
      const roundStartTime = Date.now();
      const ctxUsedBefore = this._sequence?.nextTokenIndex || 0;
      _sfResetPerGenerationTurn();
      console.log(`[ChatEngine] Calling generateResponse #1: history=${this._chatHistory.length} msgs, ctxUsedBefore=${ctxUsedBefore}`);
      _trace('generateResponse-enter', {
        round: 1,
        historyLen: this._chatHistory.length,
        ctxUsedBefore,
        genOptions: {
          maxTokens: genOptions.maxTokens,
          temperature: genOptions.temperature,
          budgets: genOptions.budgets,
          hasFunctions: !!genOptions.functions,
          functionNames: genOptions.functions ? Object.keys(genOptions.functions) : [],
        },
        chatHistory: this._chatHistory.map((m) => ({
          type: m.type,
          text: m.text || m.response || m,
        })),
      });

      let result = await this._generateResponseSafe(genOptions, {
        contextSize,
        onStreamEvent,
        functions: _useNativeFunctions ? functions : undefined,
        documentFunctionParams: _useNativeFunctions ? true : undefined,
        userMaxTokensCap: userMaxTokens,
      });
      console.log(`[ChatEngine] generateResponse #1 returned`);
      if (onContextUsage && this._sequence) {
        onContextUsage({ used: this._sequence.nextTokenIndex, total: this._context.contextSize });
      }
      const roundElapsed = (Date.now() - roundStartTime) / 1000;
      const roundTokens = result.metadata?.totalTokens ?? result.response?.length ?? 0;
      const roundTokPerSec = roundElapsed > 0 ? (roundTokens / roundElapsed).toFixed(1) : '?';
      const ctxUsedAfter = this._sequence?.nextTokenIndex || 0;
      _trace('generateResponse-return', {
        round: 1,
        stopReason: result.metadata?.stopReason,
        response: result.response,
        metadata: result.metadata,
        roundElapsedMs: roundElapsed * 1000,
        ctxUsedAfter,
        roundTokens,
      });
      const currentGpuLayers = this._model?.gpuLayers ?? '?';
      console.log(`[ChatEngine] generateResponse returned: stopReason=${result.metadata?.stopReason}, tokens=${roundTokens}, time=${roundElapsed.toFixed(1)}s, tok/s=${roundTokPerSec}, ctxUsed=${ctxUsedAfter}/${contextSize}, gpuLayers=${currentGpuLayers}`);
      // EOG DIAGNOSTIC: When stopReason is eogToken, log detailed context for root cause analysis.
      // Token count is read from `roundTokens` (computed above) which already falls back across
      // metadata.totalTokens / response.length. The previous version read `eogMeta.totalTokens`
      // which is undefined in this metadata shape, so every diagnostic printed "?" and 0.0%.
      if (result.metadata?.stopReason === 'eogToken') {
        const eogMeta = result.metadata || {};
        const respText = result.response || '';
        const lastChars = respText.length > 80 ? respText.slice(-80) : respText;
        const trimmedTail = respText.trim();
        const ctxPct = ((ctxUsedAfter / contextSize) * 100).toFixed(1);
        const genPct = (((roundTokens || 0) / (genOptions.maxTokens || 1)) * 100).toFixed(1);
        const truncatedMidWord = /\w$/.test(trimmedTail);
        // Diagnostic-only signal — never used to drive retries or any auto-recovery.
        // "Mid-word" = response ended with a letter/digit (not punctuation/whitespace),
        // which usually indicates the stop token fired before the model finished a word.
        console.warn(`[ChatEngine] EOG DIAGNOSTIC ── stopReason=eogToken`);
        console.warn(`  tokens generated: ${roundTokens}, maxTokens budget: ${genOptions.maxTokens}, used ${genPct}%`);
        console.warn(`  context: ${ctxUsedAfter}/${contextSize} (${ctxPct}%), gpuLayers=${currentGpuLayers}`);
        console.warn(`  last 80 chars of response: "${lastChars}"`);
        console.warn(`  response truncated mid-word: ${truncatedMidWord}`);
        console.warn(`  stopGenerationTriggers: ${JSON.stringify(eogMeta.stopGenerationTriggers || 'N/A')}`);
        console.warn(`  full metadata keys: ${Object.keys(eogMeta).join(', ')}`);
        // Log the chat wrapper name so we know which wrapper is active
        console.warn(`  chatWrapper: ${this._chat?.chatWrapper?.wrapperName ?? 'unknown'}`);
      }
      // Log thinking/reasoning tags separately for debugging model decision-making
      const _rawResp = result.response || '';
      const _thinkMatch = _rawResp.match(/<think>([\s\S]*?)<\/think>/) || _rawResp.match(/<reasoning>([\s\S]*?)<\/reasoning>/) || _rawResp.match(/<reflection>([\s\S]*?)<\/reflection>/);
      if (_thinkMatch) {
        console.log(`[ChatEngine] ─── MODEL THINKING ─── "${_thinkMatch[1]}"`);
      }
      if (nativeThinkFullText) {
        console.log(`[ChatEngine] ─── MODEL THINKING (native) ─── "${nativeThinkFullText.length > 500 ? nativeThinkFullText.slice(0, 500) + '...' : nativeThinkFullText}"`);
      }
      if (_streamDiag) {
        console.log(`[ChatEngine] ─── MODEL RESPONSE ─── "${_rawResp}"`);
      } else if (_rawResp.length > 0) {
        const _respPreview = _rawResp.length > 200 ? _rawResp.slice(0, 200) + '...' : _rawResp;
        console.log(`[ChatEngine] ─── MODEL RESPONSE ─── (${_rawResp.length} chars) "${_respPreview}"`);
      }

      let _genStopReason = result.metadata?.stopReason;
      let _userAbortedGeneration = _genStopReason === 'abort' || _genStopReason === 'cancelled';

      // maxTokens interrupt diagnostic: when maxTokens stops generation mid tool-call / file stream.
      if (_genStopReason === 'maxTokens') {
        if (_useNativeFunctions) {
          console.warn(`[ChatEngine] maxTokens interrupted native FC generation — totalGenTokens=${totalGenTokens}, proseGenTokens=${genTokenCount}, partial FC result discarded by node-llama-cpp`);
        }
        if (onStreamEvent) {
          onStreamEvent('generation-warning', {
            message: 'Generation hit token limit during tool call — will continue',
            suggestion: 'The model will automatically continue generating to complete the tool call.',
          });
        }
        if (_sfContentStreamActive && onStreamEvent) {
          if (_sfContentBuf) {
            onStreamEvent('file-content-token', _sfContentBuf);
            _sfContentBuf = '';
          }
          onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _sfContentFilePath, incomplete: true });
          _sfSaveContentContinuation();
          _sfContentStreamActive = false;
          console.log(`[ChatEngine] maxTokens interrupt: emitted partial file-content-end for ${_sfContentFilePath} (incomplete)`);
        }
      }

      // Seamless continuation: when maxTokens stops generation, continue from where the model left off.
      // Implements the core pipeline requirement (RULES.md Section 2): "when generation hits maxTokens,
      // the pipeline continues in the same response without user intervention."
      // Previously, continuation only existed inside the tool loop (after tool execution).
      // This adds continuation for maxTokens stops with 0 tool calls — the 15-minute silence scenario.
      let _seamlessRound = 0;
      const MAX_SEAMLESS_CONTINUATION_ROUNDS = 10;
      while (result.metadata?.stopReason === 'maxTokens' && _seamlessRound < MAX_SEAMLESS_CONTINUATION_ROUNDS) {
        _seamlessRound++;

        // Reset streaming filter state for the next generation round
        _sfBuf = ''; _sfDepth = 0; _sfActive = false; _sfConfirmed = false;
        _sfInStr = false; _sfEscaped = false; _sfLastCharWasNewlineOrStart = true;
        _sfInFence = false; _sfFenceBuf = ''; _sfFenceTickCount = 0;
        _sfFileWriteDetected = false; _sfContentStreamActive = false; _sfContentDone = false;
        _sfResetContentJsonState(); _sfContentBuf = ''; _sfContentFilePath = '';
        _sfInThink = false; _sfThinkBuf = ''; _sfThinkTagMatch = '';
        _sfFenceInThink = false;
        _sfResetPlainFenceStream();
        _sfNativeThinkActive = false;
        this._nativeThinkLogged = false;
        _sfRestoreContentContinuationAfterReset();
        // NOTE: _sfVisibleChars is NOT reset — it tracks cumulative visible chars across rounds

        // Recalculate maxTokens for this round
        const _seamlessCtxUsed = this._sequence?.nextTokenIndex || 0;
        const _seamlessCtxAvail = contextSize - _seamlessCtxUsed;
        if (_seamlessCtxAvail < 1) {
          console.log(`[ChatEngine] Seamless continuation: insufficient context (${_seamlessCtxAvail} tokens) — stopping`);
          break;
        }
        // Do not recalculate or shrink maxTokens during continuation.
        if (userMaxTokens !== Infinity) {
          genOptions.maxTokens = Math.min(userMaxTokens, _seamlessCtxAvail);
        }

        console.log(`[ChatEngine] Seamless continuation #${_seamlessRound}: maxTokens=${genOptions.maxTokens}, ctxUsed=${_seamlessCtxUsed}/${contextSize}`);

        // Continue generation — model sees its previous partial output via cleanHistory and continues
        result = await this._generateResponseSafe(genOptions, {
          contextSize,
          onStreamEvent,
          functions: _useNativeFunctions ? functions : undefined,
          documentFunctionParams: _useNativeFunctions ? true : undefined,
          userMaxTokensCap: userMaxTokens,
        });

        // Apply cleanHistory from continuation
        this._lastEvaluation = result.lastEvaluation;
        if (result.lastEvaluation?.cleanHistory) {
          this._chatHistory = result.lastEvaluation.cleanHistory;
        }

        // Update context usage display
        if (onContextUsage && this._sequence) {
          onContextUsage({ used: this._sequence.nextTokenIndex, total: this._context.contextSize });
        }

        console.log(`[ChatEngine] Seamless continuation #${_seamlessRound} returned: stopReason=${result.metadata?.stopReason}, responseLen=${result.response?.length || 0}, totalGenTokens=${totalGenTokens}`);

        // If user aborted during continuation, stop
        if (result.metadata?.stopReason === 'abort' || result.metadata?.stopReason === 'cancelled') break;
        // If continuation produced native FC calls or ended naturally, break out to tool dispatch
        if (result.metadata?.stopReason !== 'maxTokens') break;
      }

      // Update stop reason variables after seamless continuation
      _genStopReason = result.metadata?.stopReason;
      _userAbortedGeneration = _genStopReason === 'abort' || _genStopReason === 'cancelled';
      if (_seamlessRound > 0) {
        console.log(`[ChatEngine] Seamless continuation complete: ${_seamlessRound} rounds, final stopReason=${_genStopReason}, totalGenTokens=${totalGenTokens}`);
      }

      // Tool call dispatch — native function calling path first, prose JSON fallback second.
      if (executeToolFn && !_userAbortedGeneration) {
        _sfFlush();
        _sfFlushFence();

        // ── Native function calling path ──────────────────────────────────────────────
        // Used when: wrapper supports function call grammar AND stopReason === 'functionCalls'.
        // Falls through to prose parse if neither condition is met (zero regression risk).
        if (_useNativeFunctions && result.metadata?.stopReason === 'functionCalls' && result.functionCalls?.length) {
          const _nativeSessionId = this._sessionId;
          let pendingCalls = result.functionCalls;
          if (options.planMode && options.agentPhase !== 'building' && pendingCalls?.length) {
            const blockedNative = [];
            pendingCalls = pendingCalls.filter((fc) => {
              const name = fc.functionName;
              if (!PLAN_MODE_ALLOWED_TOOLS.has(name)) { blockedNative.push(name); return false; }
              if (name === 'write_file') {
                const fp = String(fc.params?.filePath || fc.params?.path || '');
                if (!isPlanFilePath(fp)) { blockedNative.push(name); return false; }
              }
              return true;
            });
            if (blockedNative.length) {
              console.log(`[ChatEngine] Plan mode — blocked native tool(s): ${blockedNative.join(', ')}`);
              this._chatHistory.push({
                type: 'user',
                text: `[System: Plan mode — blocked tools: ${blockedNative.join(', ')}. Use read/search/git and write_file for .guide/plans/*.plan.md only.]`,
              });
            }
          }
          const _ctxTokens = this._contextSize || this.modelInfo?.contextSize || 8192;

          const _findLatestModelItem = () => {
            for (let i = this._chatHistory.length - 1; i >= 0; i--) {
              if (this._chatHistory[i]?.type === 'model') return this._chatHistory[i];
            }
            return null;
          };

          while (pendingCalls && pendingCalls.length > 0) {
            if (this._sessionId !== _nativeSessionId) break;
            if (_userAbortedGeneration) break;
            this._chatHistory = result.lastEvaluation.cleanHistory;

            const modelItem = _findLatestModelItem();
            const orphanLines = [];

            const _NATIVE_FILE_WRITE_OPS = new Set(['write_file', 'create_file', 'append_to_file']);
            for (const fc of pendingCalls) {
              const toolName = fc.functionName;
              const toolParams = canonicalizeToolParams(toolName, fc.params ?? {});
              totalToolCalls++;
              console.log(`[ChatEngine] Native tool call #${totalToolCalls}: ${toolName}(${JSON.stringify(toolParams)})`);
              if (onStreamEvent) {
                onStreamEvent('tool-generating', { tool: toolName });
                onStreamEvent('tool-executing', [{ tool: toolName, params: toolParams }]);
              }

              // Emit file-content events for write operations so the UI shows FileContentBlock.
              // The prose JSON path already does this (line ~2522); native FC path was missing it,
              // causing write_file calls from Qwen/DeepSeek native FC to produce no code blocks.
              if (_NATIVE_FILE_WRITE_OPS.has(toolName) && toolParams?.content && onStreamEvent) {
                const _fp = toolParams.filePath || toolParams.path || '';
                if (
                  shouldStreamFileContentForAgent(options, _fp)
                  && !_sfStreamedFileWrites.has(_normalizePath(_fp))
                ) {
                  emitCompleteFileContentBlock(onStreamEvent, _fp, toolParams.content, options);
                }
              }

              const _toolStart = Date.now();
              let toolResult;
              try { toolResult = await executeToolFn(toolName, toolParams); }
              catch (e) { toolResult = { success: false, error: e.message }; }
              console.log(`[ChatEngine] Native tool ${toolName} completed in ${Date.now() - _toolStart}ms`);
              if (onToolCall) onToolCall({ name: toolName, params: toolParams, result: toolResult });
              if (onStreamEvent) onStreamEvent('mcp-tool-results', [{ tool: toolName, result: toolResult }]);

              const injectStr = formatToolResultForInject(toolName, toolResult, { contextTokens: _ctxTokens });
              let injected = false;

              if (modelItem && Array.isArray(modelItem.response)) {
                const unfilled = modelItem.response.filter(
                  (r) => r && r.type === 'functionCall' && (r.result === undefined || r.result === null)
                );
                const slot = unfilled[0];
                if (slot) {
                  slot.result = injectStr;
                  injected = true;
                  const slotIdx = modelItem.response.indexOf(slot);
                  console.log(`[ChatEngine] Native FC result injected → slot #${slotIdx} (${slot.name || toolName})`);
                } else {
                  console.warn(
                    `[ChatEngine] Native FC inject: no unfilled slots (${modelItem.response.filter((r) => r?.type === 'functionCall').length} total FC items)`
                  );
                }
              } else {
                console.warn(
                  `[ChatEngine] Native FC inject: no model item in history (last type=${this._chatHistory[this._chatHistory.length - 1]?.type})`
                );
              }

              if (!injected) {
                orphanLines.push(`${toolName}: ${injectStr}`);
              }
            }

            if (orphanLines.length > 0) {
              this._chatHistory.push({
                type: 'user',
                text: buildToolResultsUserMessage(orphanLines),
              });
              console.log(`[ChatEngine] ─── TOOL RESULTS → MODEL (native fallback) ─── ${orphanLines.length} result(s)`);
            } else {
              console.log(`[ChatEngine] ─── TOOL RESULTS → MODEL (native slots) ─── ${pendingCalls.length} result(s)`);
            }

            const ctxAvailNow = contextSize - (this._sequence?.nextTokenIndex || 0);
            if (userMaxTokens !== Infinity) {
              genOptions.maxTokens = Math.min(userMaxTokens, ctxAvailNow);
            }
            _sfResetPerGenerationTurn();
            result = await this._generateResponseSafe(genOptions, {
              contextSize,
              onStreamEvent,
              functions: _useNativeFunctions ? functions : undefined,
              documentFunctionParams: _useNativeFunctions ? true : undefined,
              userMaxTokensCap: userMaxTokens,
            });
            this._chatHistory = result.lastEvaluation.cleanHistory;
            if (onContextUsage && this._sequence) {
              onContextUsage({ used: this._sequence.nextTokenIndex, total: this._context.contextSize });
            }
            pendingCalls = result.metadata?.stopReason === 'functionCalls' ? result.functionCalls : null;

            // Seamless continuation inside native FC tool loop:
            // When maxTokens stops generation after tool execution, the model was mid-FC or
            // mid-prose. Without continuation, pendingCalls=null causes the loop to exit
            // silently — the 5-minute invisible generation scenario.
            let _toolLoopSeamlessRound = 0;
            const MAX_TOOL_LOOP_SEAMLESS = 5;
            while (result.metadata?.stopReason === 'maxTokens' && _toolLoopSeamlessRound < MAX_TOOL_LOOP_SEAMLESS && !_userAbortedGeneration) {
              _toolLoopSeamlessRound++;
              // Reset streaming filter state for the next generation round
              _sfBuf = ''; _sfDepth = 0; _sfActive = false; _sfConfirmed = false;
              _sfInStr = false; _sfEscaped = false; _sfLastCharWasNewlineOrStart = true;
              _sfInFence = false; _sfFenceBuf = ''; _sfFenceTickCount = 0;
              _sfFileWriteDetected = false; _sfContentStreamActive = false; _sfContentDone = false;
              _sfResetContentJsonState(); _sfContentBuf = ''; _sfContentFilePath = '';
              _sfInThink = false; _sfThinkBuf = ''; _sfThinkTagMatch = '';
              _sfFenceInThink = false;
              _sfResetPlainFenceStream();
              _sfNativeThinkActive = false;
              this._nativeThinkLogged = false;
              _sfRestoreContentContinuationAfterReset();

              const _tlCtxUsed = this._sequence?.nextTokenIndex || 0;
              const _tlCtxAvail = contextSize - _tlCtxUsed;
              if (_tlCtxAvail < 1) {
                console.log(`[ChatEngine] Tool-loop seamless: insufficient context (${_tlCtxAvail} tokens) — stopping`);
                break;
              }
              if (userMaxTokens !== Infinity) {
                genOptions.maxTokens = Math.min(userMaxTokens, _tlCtxAvail);
              }
              console.log(`[ChatEngine] Tool-loop seamless continuation #${_toolLoopSeamlessRound}: maxTokens=${genOptions.maxTokens}, ctxUsed=${_tlCtxUsed}/${contextSize}`);

              result = await this._generateResponseSafe(genOptions, {
                contextSize,
                onStreamEvent,
                functions: _useNativeFunctions ? functions : undefined,
                documentFunctionParams: _useNativeFunctions ? true : undefined,
                userMaxTokensCap: userMaxTokens,
              });
              this._chatHistory = result.lastEvaluation.cleanHistory;
              if (onContextUsage && this._sequence) {
                onContextUsage({ used: this._sequence.nextTokenIndex, total: this._context.contextSize });
              }
              pendingCalls = result.metadata?.stopReason === 'functionCalls' ? result.functionCalls : null;
              console.log(`[ChatEngine] Tool-loop seamless #${_toolLoopSeamlessRound} returned: stopReason=${result.metadata?.stopReason}, pendingCalls=${pendingCalls?.length ?? 0}`);

              // If the continuation produced function calls, break out of seamless loop
              // to process them in the outer tool loop
              if (pendingCalls) break;
              // If stop reason changed from maxTokens (e.g., eogToken, natural), stop
              if (result.metadata?.stopReason !== 'maxTokens') break;
            }
            if (_toolLoopSeamlessRound > 0) {
              console.log(`[ChatEngine] Tool-loop seamless continuation complete: ${_toolLoopSeamlessRound} rounds, final stopReason=${result.metadata?.stopReason}`);
            }
          }
          this._lastEvaluation = result.lastEvaluation;
        }
        // ── Prose JSON fallback path (unchanged) ──────────────────────────────────────
        // Used when native functions not active or stopReason !== 'functionCalls'.
        else {

        let roundStart = 0;
        let parsedCalls = []; // Hoisted to function scope for refusal correction access
        let repairRetryPending = false;
        let preRepairCallsForUi = [];
        parsedCalls = parseToolCalls(fullResponse);

        console.log(`[ChatEngine] Tool parse: found ${parsedCalls.length} tool call(s) in ${fullResponse.length} chars of model output`);
        // When 0 calls found, log response preview for diagnostics
        if (parsedCalls.length === 0 && fullResponse.length > 20) {
          console.warn(`[ChatEngine] ⚠ 0 tool calls parsed — model output preview: "${fullResponse.replace(/\n/g, '\\n')}"`);
        }
        if (parsedCalls.length === 0 && looksLikeToolAttempt(fullResponse)) {
          const closestHint = suggestClosestToolName(fullResponse);
          this._chatHistory.push({
            type: 'user',
            text: `[System: Tool call could not be parsed. Retry with valid JSON: {"tool":"<name>","params":{...}}.${closestHint ? ` ${closestHint}` : ''}]`,
          });
        }
        if (parsedCalls.length > 0) {
          preRepairCallsForUi = parsedCalls;
          const { repaired, issues } = repairToolCalls(parsedCalls, fullResponse);
          if (repaired.length === 0 && issues.length > 0) {
            console.warn(`[ChatEngine] All ${parsedCalls.length} tool call(s) failed validation — feeding errors back to model`);
            this._chatHistory.push({
              type: 'user',
              text: `[System: Tool Validation Failed]\n${issues.join('\n')}\n\nRetry with valid tool parameters.`,
            });
            repairRetryPending = true;
            if (onStreamEvent && preRepairCallsForUi.length) {
              onStreamEvent('tool-executing', preRepairCallsForUi.map((c) => ({ tool: c.tool, params: c.params })));
              onStreamEvent('mcp-tool-results', preRepairCallsForUi.map((c) => ({
                tool: c.tool,
                result: { success: false, error: issues.join('; ') },
              })));
            }
          }
          parsedCalls = filterWebWorkspaceToolConflict(repaired);
          console.log(`[ChatEngine] Tool calls after repair/filter: ${parsedCalls.length} — [${parsedCalls.map(c => c.tool).join(', ')}]`);
        }

        // Hoisted outside while loop — avoids reallocating a new Set on every tool-call iteration
        const FILE_MODIFY_OPS_SET = new Set(['write_file', 'create_file', 'append_to_file', 'edit_file', 'replace_in_file']);
        const FILE_WRITE_OPS = new Set(['write_file', 'create_file', 'append_to_file']);

        // Ask mode: discard any tool calls — model should only be responding conversationally
        if (options.askOnly && parsedCalls.length > 0) {
          console.log(`[ChatEngine] Ask mode — discarding ${parsedCalls.length} tool call(s) from model output`);
          parsedCalls = [];
        }
        if (options.planMode && options.agentPhase !== 'building' && parsedCalls.length > 0) {
          const { calls: planCalls, blocked } = filterPlanModeToolCalls(parsedCalls);
          if (blocked.length > 0) {
            console.log(`[ChatEngine] Plan mode — blocked ${blocked.length} tool call(s): [${blocked.map(c => c.tool).join(', ')}]`);
            this._chatHistory.push({
              type: 'user',
              text: `[System: Plan mode — only read/search/git tools and write_file for .guide/plans/*.plan.md are allowed. Blocked: ${blocked.map(c => c.tool).join(', ')}. Continue planning with permitted tools.]`,
            });
          }
          parsedCalls = planCalls;
        }

        console.log(`[ChatEngine] Tool loop ENTER: ${parsedCalls.length} parsed call(s), repairRetry=${repairRetryPending}`);
        let planArtifactThisTurn = false;
        while (parsedCalls.length > 0 || repairRetryPending) {
          const skipToolExecution = repairRetryPending;
          if (repairRetryPending) {
            repairRetryPending = false;
            console.log('[ChatEngine] Tool loop: repair retry — continuing generation without executing invalid calls');
          }
          if (isCancelled()) {
            _userAbortedGeneration = true;
            console.log('[ChatEngine] Tool loop aborted — user cancelled');
            break;
          }
          const sessionAtStart = this._sessionId;
          console.log(`[ChatEngine] Tool loop ITERATION: ${parsedCalls.length} call(s), sessionId=${sessionAtStart}, skipExec=${skipToolExecution}`);
          // Notify UI so ToolCallCards appear for each tool call (spinner state)
          if (!skipToolExecution && onStreamEvent) {
            onStreamEvent('tool-executing', parsedCalls.map(c => ({ tool: c.tool, params: c.params })));
          }

          const toolResultLines = [];
          // fileReadResults drives the structural "related files" injection below —
          // when the model reads a source file, we follow its imports so it can see
          // the dependencies without having to issue extra read_file calls. This is
          // a content channel, not a guard clause.
          const fileReadResults = []; // { filePath, content }

          if (!skipToolExecution) {
          for (const call of parsedCalls) {
            if (isCancelled()) {
              _userAbortedGeneration = true;
              console.log('[ChatEngine] Tool loop aborted before tool execution — user cancelled');
              break;
            }
            console.log(`[ChatEngine] Tool loop processing: ${call.tool}`);
            // No iteration cap — context window naturally bounds the loop
            totalToolCalls++;

            console.log(`[ChatEngine] Tool call #${totalToolCalls}: ${call.tool}(${JSON.stringify(call.params)})`);
            const _toolExecStart = Date.now();

            // Diagnostic: log browser click details to trace repeated-click loops
            if (call.tool === 'browser_click') {
              const refVal = call.params.elementRef || call.params.elementId || call.params.ref || call.params.selector || call.params.id || '?';
              console.log(`[ChatEngine] browser_click detail: ref=${refVal}, text="${call.params.text || ''}"`);
            }

            // Emit file-content events for file write/edit operations so the UI
            // can show a FileContentBlock / FileDiffBlock with syntax highlighting
            if (FILE_WRITE_OPS.has(call.tool) && call.params?.content && onStreamEvent) {
              const filePath = call.params.filePath || call.params.path || '';
              const _np = _normalizePath(filePath);
              if (
                shouldStreamFileContentForAgent(options, filePath)
                && !_sfStreamedFileWrites.has(_np)
                && !_sfProsedFileWrites.has(_np)
              ) {
                emitCompleteFileContentBlock(onStreamEvent, filePath, call.params.content, options);
              }
            }
            if (FILE_EDIT_OPS.has(call.tool) && call.params?.newText != null && onStreamEvent) {
              const filePath = call.params.filePath || call.params.path || '';
              if (shouldStreamFileContentForAgent(options, filePath)) {
                emitCompleteFileContentBlock(onStreamEvent, filePath, call.params.newText, options, {
                  op: 'edit',
                  oldText: call.params.oldText || '',
                  newText: call.params.newText,
                });
              }
            }
            let toolResult;
            console.log(`[ChatEngine] Executing toolFn: ${call.tool}`);
            try {
              toolResult = await executeToolFn(call.tool, call.params);
              console.log(`[ChatEngine] ToolFn ${call.tool} succeeded`);
            } catch (toolErr) {
              console.error(`[ChatEngine] ToolFn ${call.tool} threw: ${toolErr.message}`);
              toolResult = { success: false, error: toolErr.message };
            }
            const _toolExecMs = Date.now() - _toolExecStart;
            console.log(`[ChatEngine] Tool #${totalToolCalls} ${call.tool} executed in ${_toolExecMs}ms, success=${toolResult?.success !== false}`);


            // Track recently-written files so we can inject content on run_command failure.
            // Root cause of write_file loop: _writeFile returns {success:true} with NO content.
            // After run_command SyntaxError, model has zero visibility into actual file content
            // and re-writes identical broken code. Injecting the content closes the information gap.
            if (FILE_WRITE_OPS.has(call.tool) && toolResult?.success !== false && call.params?.content) {
              const writtenPath = call.params.filePath || call.params.path || toolResult?.path || '';
              if (writtenPath) {
                this._recentlyWrittenFiles.set(writtenPath, call.params.content);
              }
            }
            // On run_command failure, check if the command references a recently-written file.
            // If so, inject the file's actual content so the model can see what's wrong.
            if (call.tool === 'run_command' && toolResult?.success === false && this._recentlyWrittenFiles.size > 0) {
              const cmdStr = (call.params?.command || '').toLowerCase();
              for (const [fp, content] of this._recentlyWrittenFiles) {
                const fileName = fp.split(/[\\/]/).pop() || '';
                if (cmdStr.includes(fileName.toLowerCase()) || cmdStr.includes(fp.toLowerCase().replace(/\\/g, '/'))) {
                  const MAX_CONTENT_INJECT = 3000;
                  const snippet = content.length > MAX_CONTENT_INJECT
                    ? content.slice(0, MAX_CONTENT_INJECT) + '\n... [truncated]'
                    : content;
                  const inject = `\n\n[SYSTEM: The file "${fileName}" was just written by you and the command failed. Here is the ACTUAL content currently in the file — compare it with what you intended to write]:\n${snippet}`;
                  if (typeof toolResult.message === 'string') {
                    toolResult.message += inject;
                  } else if (typeof toolResult.error === 'string') {
                    toolResult.error += inject;
                  } else if (typeof toolResult.output === 'string') {
                    toolResult.output += inject;
                  }
                  console.log(`[ChatEngine] Injected recently-written file content for ${fileName} into run_command failure result`);
                  break;
                }
              }
            }

            // Log browser click results for diagnostics
            if (call.tool === 'browser_click' && toolResult?.success) {
              console.log(`[ChatEngine] browser_click result: clicked="${toolResult.clicked || '?'}", navigated=${toolResult.navigated}, newTab=${toolResult.newTab || false}, url=${toolResult.url || '?'}`);
            }

            // Collect file read results for multi-file context awareness
            if ((call.tool === 'read_file' || call.tool === 'edit_file') && toolResult?.success !== false) {
              const filePath = call.params?.filePath || call.params?.path || '';
              const content = typeof toolResult === 'string' ? toolResult
                : (toolResult?.content || toolResult?.data || JSON.stringify(toolResult));
              if (filePath && content) {
                fileReadResults.push({ filePath, content: String(content) });
              }
            }

            const injectPayload = call.tool === 'list_directory'
              ? trimListDirectoryInjectPayload(toolResult)
              : toolResult;
            const resultStr = typeof injectPayload === 'string' ? injectPayload : JSON.stringify(injectPayload);
            console.log(`[ChatEngine] Tool result for ${call.tool}: ${resultStr}`);
            if (onToolCall) onToolCall({ name: call.tool, params: call.params, result: toolResult });

            // Update ToolCallCard with result (check mark or error)
            if (onStreamEvent) {
              onStreamEvent('mcp-tool-results', [{ tool: call.tool, result: toolResult }]);
            }

            if (options.planMode && options.agentPhase !== 'building' && toolResult?.success !== false) {
              const fp = call.params?.filePath || call.params?.path || '';
              if (
                (call.tool === 'write_file' && isPlanFilePath(fp))
                || (call.tool === 'edit_file' && isPlanFilePath(fp))
                || call.tool === 'write_todos'
              ) {
                planArtifactThisTurn = true;
              }
            }

            let injectResult = resultStr;
            // Lint auto-fix — if any file-modification tool returned diagnostic errors,
            // inject a human-readable correction instruction AND emit a frontend event for the UI pill.
            if (FILE_MODIFY_OPS_SET.has(call.tool) && toolResult?.diagnostics?.errors > 0 && options.autoLintFix !== false) {
              const { errors, details } = toolResult.diagnostics;
              const detailStr = details?.length ? details.join('; ') : `${errors} error(s)`;
              const filePath = call.params?.filePath || call.params?.path || 'file';
              injectResult += `\n[LINT ERRORS IN ${filePath} — MUST FIX IMMEDIATELY: ${detailStr}. Fix ALL errors before proceeding.]`;
              if (onStreamEvent) {
                onStreamEvent('file-content-lint', {
                  filePath,
                  diagnostics: toolResult.diagnostics,
                });
              }
              console.log(`[ChatEngine] Lint auto-fix: ${errors} error(s) in ${filePath} — correction injected into tool result`);
            }
            // Screenshot handling: try vision captioning first, otherwise compact note
            // Vision server loads on demand via captionImage() → _ensureRunning(),
            // then unloads after captioning to free VRAM. No need to check isReady.
            if (call.tool === 'browser_screenshot' && toolResult?.success && toolResult?.screenshot) {
              if (this.modelInfo?.visionAvailable) {
                try {
                  const caption = await visionServer.captionImage(
                    toolResult.screenshot,
                    toolResult.mimeType || 'image/png',
                    'Describe this screenshot in detail. List all visible text, buttons, links, input fields, and interactive elements with their labels.'
                  );
                  if (caption) {
                    injectResult = JSON.stringify({ success: true, visionCaption: caption });
                    console.log(`[ChatEngine] Screenshot captioned via vision server: ${caption.length} chars`);
                  } else {
                    injectResult = '{"success":true,"note":"Screenshot captured. Use browser_snapshot for a detailed text description of the page."}';
                  }
                } catch (visionErr) {
                  console.error(`[ChatEngine] Vision caption failed: ${visionErr.message}`);
                  injectResult = '{"success":true,"note":"Screenshot captured. Use browser_snapshot for a detailed text description of the page."}';
                }
              } else {
                injectResult = '{"success":true,"note":"Screenshot captured. Use browser_snapshot for a detailed text description of the page."}';
              }
            }
            // PL2: Context-proportional inject cap — 25% share per tool, 40% absolute max per call (no 8k floor).
            const ctxTokens = this._contextSize || this.modelInfo?.contextSize || 8192;
            const ctxChars = ctxTokens * 4;
            const TOOL_RESULT_SHARE = 0.25;
            const MAX_TOOL_SHARE = 0.40;
            const baseCap = Math.floor(ctxChars * TOOL_RESULT_SHARE);
            const multiplier = TOOL_INJECT_MULTIPLIERS[call.tool] || 1.0;
            const injectCap = Math.min(
              Math.floor(baseCap * multiplier),
              Math.floor(ctxChars * MAX_TOOL_SHARE),
            );
            if (injectResult.length > injectCap) {
              // PL1: Smart truncation for browser snapshots — preserve ALL interactive elements
              // (the model needs every ref to make correct decisions) and truncate only the page text.
              // For non-browser tools, use the original flat cap.
              if (call.tool === 'browser_snapshot' || call.tool === 'browser_navigate' || call.tool === 'browser_click' || call.tool === 'browser_type') {
                const pageTextIdx = injectResult.indexOf('\nPage text:\n');
                if (pageTextIdx !== -1) {
                  const elementSection = injectResult.substring(0, pageTextIdx + 12);
                  const textSection = injectResult.substring(pageTextIdx + 12);
                  const budgetForText = injectCap - elementSection.length;
                  if (budgetForText > 500) {
                    const headSize = Math.floor(budgetForText * 0.7);
                    const tailSize = budgetForText - headSize - 60;
                    injectResult = elementSection + textSection.substring(0, headSize)
                      + '\n[... middle section omitted for context size — call browser_scroll to see more]\n'
                      + textSection.substring(Math.max(headSize, textSection.length - tailSize));
                  } else {
                    injectResult = elementSection + textSection.substring(0, budgetForText)
                      + '\n[... result truncated — call browser_scroll to see more content]';
                  }
                } else {
                  injectResult = injectResult.slice(0, injectCap)
                    + '\n[... result truncated by system for context size; use browser_scroll to see more]';
                }
              } else {
                injectResult = injectResult.slice(0, injectCap)
                  + '\n[... result truncated by system for context size; use only text above]';
              }
            }
            if (call.tool === 'write_todos' && toolResult?.success !== false) {
              const allTodos = toolResult?.allTodos || toolResult?.created;
              if (Array.isArray(allTodos) && allTodos.length > 0) {
                const idList = allTodos.map((t) => `id ${t.id}: ${(t.text || '').slice(0, 60)}`).join('; ');
                injectResult += `\nTodos: ${idList}. Use update_todo(id, status) in-progress/done as you work.`;
              }
            }
            if (call.tool === 'read_file' && toolResult?.success !== false) {
              const fp = toolResult.path || call.params?.filePath || call.params?.path || '';
              const totalLines = toolResult.totalLines;
              const contentLen = typeof toolResult.content === 'string' ? toolResult.content.length : 0;
              const sizeKb = contentLen > 0 ? Math.round(contentLen / 1024) : null;
              const meta = [
                'read_file: success',
                fp ? `path=${fp}` : '',
                totalLines != null ? `totalLines=${totalLines}` : '',
                sizeKb != null ? `size=~${sizeKb}KB` : '',
              ].filter(Boolean).join(', ');
              injectResult = `${meta} — full file returned.\n${injectResult}`;
            }
            if (call.tool === 'write_file' && toolResult?.success !== false) {
              const writtenPath = call.params?.filePath || call.params?.path || toolResult?.path || '';
              if (writtenPath && this._recentlyWrittenFiles.has(writtenPath)) {
                const fileName = writtenPath.split(/[\\/]/).pop() || writtenPath;
                injectResult += `\n[Note: write_file succeeded for ${fileName}. File is on disk; avoid full rewrite — use edit_file for tweaks.]`;
              }
            }

            toolResultLines.push(`${call.tool}: ${injectResult}`);

            {
              const fp = stableToolFingerprint(call.tool, call.params);
              if (!this._toolExecFingerprints) this._toolExecFingerprints = [];
              this._toolExecFingerprints.push(fp);
              if (this._toolExecFingerprints.length > 3) {
                this._toolExecFingerprints = this._toolExecFingerprints.slice(-3);
              }
            }
          }
          } // end skipToolExecution guard

          if (isCancelled()) {
            _userAbortedGeneration = true;
            console.log('[ChatEngine] Tool loop exiting after tool batch — user cancelled');
            break;
          }


          // Update evaluation state and chat history from last generation
          this._lastEvaluation = result.lastEvaluation;
          if (result.lastEvaluation?.cleanHistory) {
            this._chatHistory = result.lastEvaluation.cleanHistory;
          }

          // Feed tool results back to the model so it knows what happened.
          //
          // ARCHITECTURE NOTE: there is intentionally NO conditional "grounding"
          // paragraph, NO "all calls failed" directive, NO "browser failures"
          // directive, NO "new tab opened" directive, NO fetch URL list, and NO
          // file-read warning appended to this message. Every previous version
          // of those paragraphs was a detection-driven band-aid that fixed what
          // happened AFTER the model got confused. Each tool result line already
          // contains its own success/error text (`tool: {"success": false, ...}`),
          // so the model can see exactly what failed without us re-explaining it
          // every round. The general response strategy ("after web_search, fetch
          // top results"; "after browser_navigate, snapshot"; "do not narrate
          // failures to the user") lives in SYSTEM_PROMPT once, not in every
          // tool-results turn. See `## When to use tools` and `## BROWSER
          // WORKFLOW` in the system prompt for the canonical guidance.

          // ─── Multi-file context awareness ───
          // After read_file or edit_file, parse the file's imports and inject
          // related files into the tool results. This gives the model visibility
          // into imported modules without it having to explicitly read each one.
          // Capped at 3 files × MAX_FILE_CONTEXT chars to avoid context bloat.
          const MAX_RELATED_FILES = 3;
          const MAX_FILE_CONTEXT = 4000;
          const relatedFileLines = [];
          const seenRelatedPaths = new Set();

          for (const { filePath, content } of fileReadResults) {
            if (!filePath || !content) continue;

            // Language-agnostic import detection
            const importPatterns = [
              /(?:import\s+.*?\s+from\s+['"])([^'"]+)(?:['"])/g,           // ES modules
              /(?:import\s+['"])([^'"]+)(?:['"])/g,                         // side-effect imports
              /(?:require\s*\(\s*['"])([^'"]+)(?:['"]\s*\))/g,            // CommonJS
              /(?:#include\s+[<"])([^>"]+)(?:[>"])/g,                       // C/C++
              /(?:from\s+([a-zA-Z_][\w.]*)\s+import)/g,                    // Python
            ];

            const importPaths = new Set();
            for (const pat of importPatterns) {
              pat.lastIndex = 0;
              let m;
              while ((m = pat.exec(content)) !== null) {
                const imp = m[1];
                // Skip node built-ins and package imports (no path separator)
                if (imp && (imp.startsWith('.') || imp.startsWith('/')) && !seenRelatedPaths.has(imp)) {
                  importPaths.add(imp);
                }
              }
            }

            // Try to resolve and read each import (up to MAX_RELATED_FILES total)
            for (const relPath of importPaths) {
              if (relatedFileLines.length >= MAX_RELATED_FILES) break;
              seenRelatedPaths.add(relPath);
              try {
                const resolvedPath = path.resolve(path.dirname(filePath), relPath);
                // Try with common extensions if the import has no extension
                const candidates = [resolvedPath];
                if (!path.extname(resolvedPath)) {
                  candidates.push(
                    resolvedPath + '.js', resolvedPath + '.jsx', resolvedPath + '.ts',
                    resolvedPath + '.tsx', resolvedPath + '.py', resolvedPath + '.json',
                    resolvedPath + '.css', resolvedPath + '.html',
                    path.join(resolvedPath, 'index.js'), path.join(resolvedPath, 'index.ts'),
                    path.join(resolvedPath, 'index.jsx'), path.join(resolvedPath, 'index.tsx'),
                  );
                }
                for (const candidate of candidates) {
                  if (relatedFileLines.length >= MAX_RELATED_FILES) break;
                  try {
                    const stat = fs.statSync(candidate);
                    if (stat.isFile() && stat.size < 100000) { // skip huge files
                      let relContent = fs.readFileSync(candidate, 'utf8');
                      if (relContent.length > MAX_FILE_CONTEXT) {
                        relContent = relContent.slice(0, MAX_FILE_CONTEXT) + '\n… [truncated]';
                      }
                      relatedFileLines.push(`[Related file: ${candidate}]\n${relContent}`);
                      break;
                    }
                            } catch (e) { /* file doesn't exist, try next candidate */ }
                }
              } catch (e) { /* path resolution failed, skip */ }
            }
          }

          const relatedSection = relatedFileLines.length > 0
            ? '\n\n--- Related files (auto-injected for context) ---\n' + relatedFileLines.join('\n\n---\n\n')
            : '';

          // Inject any pending user interrupt message into the tool results.
          // The interrupt is the user's most recent direction. It is delivered ONCE,
          // at the head of the next [Tool Results] message, and then cleared. We do
          // NOT re-echo the user's original or interrupt message back into context on
          // any subsequent round — the chat history already preserves user turns at
          // their natural positions, and re-injecting them creates recursive attention
          // patterns that cause the model to ignore newer user messages and to emit
          // <|im_end|> at the same offsets as the echoes (mid-word truncation).
          let userInterruptPrefix = '';
          const hadUserInterrupt = !!this._pendingUserMessage;
          if (this._pendingUserMessage) {
            userInterruptPrefix = `[USER INTERRUPT — OBEY THIS IMMEDIATELY]: ${this._pendingUserMessage}\n\n`;
            this._toolRoundCount = 0; // reset round count when user redirects mid-loop
            this._toolExecFingerprints = [];
            this._pendingUserMessage = null;
          }
          this._toolRoundCount++;

          const fps = this._toolExecFingerprints || [];
          const duplicateHint = fps.length >= 2 && fps.every((f) => f === fps[0])
            ? `${DUPLICATE_TOOL_HINT_MESSAGE}\n\n`
            : '';

          let todoListPrefix = '';
          const activeTodos = typeof options.getActiveTodos === 'function' ? options.getActiveTodos() : [];
          const executedToolNames = skipToolExecution ? [] : parsedCalls.map((c) => c.tool);
          if (!skipToolExecution) {
            if (executedToolNames.some((t) => t === 'update_todo' || t === 'write_todos')) {
              this._consecutiveToolsWithoutTodoUpdate = 0;
            } else if (executedToolNames.length > 0 && Array.isArray(activeTodos) && activeTodos.length > 0) {
              this._consecutiveToolsWithoutTodoUpdate = (this._consecutiveToolsWithoutTodoUpdate || 0) + 1;
            }
          }
          const todoProgressHint = buildTodoProgressHint(
            activeTodos,
            executedToolNames,
            this._consecutiveToolsWithoutTodoUpdate || 0,
          );
          if (todoProgressHint) {
            todoListPrefix = todoProgressHint;
          }

          if (this._sessionId !== sessionAtStart) {
            console.warn(`[ChatEngine] Session changed during tool execution (was ${sessionAtStart}, now ${this._sessionId}) — dropping stale tool results`);
            break;
          }

          if (!skipToolExecution) {
          this._chatHistory.push({
            type: 'user',
            text: `${userInterruptPrefix}${todoListPrefix}${duplicateHint}[System: Tool Results]\nThe tools below have ALREADY been executed. Do not repeat these actions or re-narrate work that is already complete. Give a brief summary of outcomes, then either call the next tool if more work is needed or give a short final answer. Do NOT enumerate long lists of hypothetical future options or features.\n\n${toolResultLines.join('\n')}${relatedSection}`,
          });
          console.log(`[ChatEngine] ─── TOOL RESULTS → MODEL ─── ${toolResultLines.length} result(s), ${relatedFileLines.length} related file(s), interrupt=${hadUserInterrupt}`);
          } else {
            console.log('[ChatEngine] Repair retry — skipping tool results push (validation error already in history)');
          }
          // Log compact summaries — browser snapshots bloat logs with full DOM
          const compactSummaries = toolResultLines.map(line => {
            const colonIdx = line.indexOf(':');
            if (colonIdx === -1) return line;
            const toolName = line.substring(0, colonIdx);
            if (toolName === 'browser_snapshot' || toolName === 'browser_navigate' || toolName === 'browser_click' || toolName === 'browser_type') {
              try {
                const resultStr = line.substring(colonIdx + 1).trim();
                const parsed = JSON.parse(resultStr);
                const snapText = parsed.text || parsed.snapshot || '';
                const elCount = Array.isArray(parsed.elements) ? parsed.elements.length
                  : (snapText.match(/\[ref=\d+\]/g) || []).length;
                return `${toolName}: URL=${parsed.url || '?'}, title="${(parsed.title || '').slice(0, 80)}", elements=${elCount}`;
              } catch { return `${toolName}: (snapshot — see full result in tool output)`; }
            }
            return line.length > 200 ? line.substring(0, 200) + '...' : line;
          });
          console.log(`[ChatEngine] Tool result summary: ${compactSummaries.join(' | ')}`);

          // ─── Context compaction between tool rounds ───
          // Root cause of slow prefill: each round re-prefills the ENTIRE history.
          // Browser snapshots are the worst offender — 5-10KB of page DOM per result.
          // The model only needs the CURRENT page state, not full DOMs from 5 pages ago.
          // Solution: strip snapshot text from old results, keep only URL/title/status.
          // Only the most recent tool result message retains full content.
          if (this._chatHistory.length > 6) {
            const toolResultIndices = [];
            for (let i = 0; i < this._chatHistory.length; i++) {
              if (this._chatHistory[i].type === 'user' && (this._chatHistory[i].text.startsWith('[System: Tool Results]') || this._chatHistory[i].text.startsWith('[Tool Results]'))) {
                toolResultIndices.push(i);
              }
            }
            // Process all but the most recent tool result message
            if (toolResultIndices.length > 1) {
              for (let j = 0; j < toolResultIndices.length - 1; j++) {
                const idx = toolResultIndices[j];
                const full = this._chatHistory[idx].text;
                if (full.length > 500) {
                  const lines = full.split('\n');
                  const summaryLines = lines.filter(l => /^[a-z_]+:/.test(l)).map(l => {
                    const colonIdx = l.indexOf(':');
                    const toolName = l.substring(0, colonIdx);
                    const result = l.substring(colonIdx + 1).trim();
                    const isErr = result.startsWith('{"success":false') || result.includes('"error"');
                    // Browser snapshots: strip full page DOM, keep only URL + title
                    if (toolName === 'browser_snapshot' && !isErr) {
                      try {
                        const parsed = JSON.parse(result);
                        const url = parsed.url || '';
                        const title = parsed.title || '';
                        return `browser_snapshot: URL=${url}, title=${title} (page content removed — already on a different page)`;
                      } catch { return `browser_snapshot: OK (old page)`; }
                    }
                    // Browser navigate: strip snapshot, keep URL + title + status
                    if (toolName === 'browser_navigate' && !isErr) {
                      try {
                        const parsed = JSON.parse(result);
                        const url = parsed.url || '';
                        const title = parsed.title || '';
                        const status = parsed.httpStatus || '';
                        return `browser_navigate: navigated to ${url}${title ? ` (${title})` : ''}${status ? ` HTTP ${status}` : ''}`;
                      } catch { return `browser_navigate: OK`; }
                    }
                    // Browser click: keep what was clicked and resulting URL
                    if (toolName === 'browser_click' && !isErr) {
                      try {
                        const parsed = JSON.parse(result);
                        const clicked = parsed.clicked || '';
                        const url = parsed.url || '';
                        return `browser_click: clicked "${clicked}"${url ? `, now at ${url}` : ' (no navigation)'}`;
                      } catch { return `browser_click: OK`; }
                    }
                    // Browser type: keep what was typed
                    if (toolName === 'browser_type' && !isErr) {
                      try {
                        const parsed = JSON.parse(result);
                        const url = parsed.url || '';
                        return `browser_type: typed${url ? `, now at ${url}` : ''}`;
                      } catch { return `browser_type: OK`; }
                    }
                    // read_file: preserve file path and content excerpt so model doesn't re-read same file
                    if (toolName === 'read_file' && !isErr) {
                      try {
                        const parsed = JSON.parse(result);
                        const filePath = parsed.path || '';
                        const content = (parsed.content || '').substring(0, 300);
                        return `read_file: ${filePath}${content ? ` — ${content}` : ''}`;
                      } catch { return `read_file: OK`; }
                    }
                    // list_directory: preserve directory path so model knows it already listed it
                    if (toolName === 'list_directory' && !isErr) {
                      try {
                        const parsed = JSON.parse(result);
                        const dirPath = parsed.path || '';
                        const entries = (parsed.entries || []).map(e => e.name || e).slice(0, 15).join(', ');
                        return `list_directory: ${dirPath} — ${entries}`;
                      } catch { return `list_directory: OK`; }
                    }
                    // ask_question: preserve the full answer — it contains user-provided data
                    // (credentials, choices, instructions) that must survive compaction
                    if (toolName === 'ask_question' && !isErr) {
                      try {
                        const parsed = JSON.parse(result);
                        const answer = parsed.answer || '';
                        return `ask_question: ${answer.substring(0, 1000)}${answer.length > 1000 ? '...' : ''}`;
                      } catch { return `ask_question: OK`; }
                    }
                    return `${toolName}: ${isErr ? 'FAILED' : 'OK'}`;
                  });
                  this._chatHistory[idx] = {
                    type: 'user',
                    text: `[Earlier Tool Results (summarized)]\n${summaryLines.join('\n')}`,
                  };
                }
              }
            }
          }

          // KV cache always preserved between tool rounds.
          // Previously cleared after write tools (attention-pattern contamination theory),
          // but this caused 40-90s full-prefill penalties. Root cause (sampling) was fixed
          // in the generation-speed parity fix. Preserving cache = fast prefill every round.
          console.log('[ChatEngine] KV cache preserved — fast prefill enabled');

          _sfFlush();
          _sfFlushFence();

          // Reset streaming filter state for the next generation round
          _sfBuf = '';
          _sfDepth = 0;
          _sfActive = false;
          _sfConfirmed = false;
          _sfInStr = false;
          _sfEscaped = false;
          _sfLastCharWasNewlineOrStart = true;
          _sfInFence = false;
          _sfFenceBuf = '';
          _sfFenceTickCount = 0;
          _sfFileWriteDetected = false;
          _sfContentStreamActive = false;
          _sfContentDone = false;
          _sfResetContentJsonState();
          _sfContentBuf = '';
          _sfContentFilePath = '';
          // Keep cumulative visible count across tool-loop continuations (matches seamless continuation).
          _sfInThink = false;
          _sfThinkBuf = '';
          _sfThinkTagMatch = '';
          _sfFenceInThink = false;
          _sfResetPlainFenceStream();
          _sfNativeThinkActive = false;

          // Generate continuation — model sees tool results and can issue more tool calls
          if (isCancelled()) {
            _userAbortedGeneration = true;
            console.log('[ChatEngine] Tool loop aborted before continuation — user cancelled');
            break;
          }
          if (planArtifactThisTurn) {
            options.planReady = true;
            options.planFileExists = true;
          }
          const skipPlanToolContinuation = options.planMode && options.agentPhase !== 'building' && (
            planArtifactThisTurn
            || resolvePlanPhase({
              planMode: true,
              agentPhase: options.agentPhase,
              planReady: !!options.planReady,
              planFileExists: !!options.planFileExists,
            }) === 'plan_ready'
          );
          if (skipPlanToolContinuation) {
            console.log('[ChatEngine] Plan mode — skipping tool-loop continuation (plan ready; user must click Build)');
            parsedCalls = [];
            repairRetryPending = false;
            break;
          }
          // Recalculate maxTokens for this round — tool results consumed context space
          const ctxUsedNow = this._sequence?.nextTokenIndex || 0;
          const ctxAvailNow = contextSize - ctxUsedNow;
          if (userMaxTokens !== Infinity) {
            genOptions.maxTokens = Math.min(userMaxTokens, ctxAvailNow);
          }
          const _prefillStart = Date.now();
          console.log(`[ChatEngine] Continuation maxTokens: ${genOptions.maxTokens} (ctx used: ${ctxUsedNow}/${contextSize})`);

          roundStart = fullResponse.length;
          _sfResetPerGenerationTurn();
          console.log(`[ChatEngine] Calling generateResponse CONTINUATION: history=${this._chatHistory.length} msgs`);
          result = await this._generateResponseSafe(genOptions, {
            contextSize,
            onStreamEvent,
            functions: _useNativeFunctions ? functions : undefined,
            documentFunctionParams: _useNativeFunctions ? true : undefined,
            userMaxTokensCap: userMaxTokens,
          });
          console.log(`[ChatEngine] generateResponse CONTINUATION returned: stopReason=${result.metadata?.stopReason}, responseLen=${result.response?.length || 0}`);
          if (onContextUsage && this._sequence) {
            onContextUsage({ used: this._sequence.nextTokenIndex, total: this._context.contextSize });
          }
          const _prefillAndGenMs = Date.now() - _prefillStart;
          _trace('generateResponse-return', {
            round: 'continuation',
            stopReason: result.metadata?.stopReason,
            response: result.response,
            metadata: result.metadata,
            prefillAndGenMs: _prefillAndGenMs,
            ctxUsed: ctxUsedNow,
          });
          console.log(`[ChatEngine] Continuation after tools: stopReason=${result.metadata?.stopReason}, responseLen=${result.response?.length || 0}, prefill+gen=${_prefillAndGenMs}ms, ctxUsed=${ctxUsedNow}`);
          // EOG DIAGNOSTIC (continuation): same shape as the primary diagnostic above.
          // Reads `roundTokens` (recomputed from this round's metadata) so the printed
          // token count is real, not the always-undefined eogMeta.totalTokens.
          if (result.metadata?.stopReason === 'eogToken') {
            const eogMeta = result.metadata || {};
            const respText = result.response || '';
            const lastChars = respText.length > 80 ? respText.slice(-80) : respText;
            const roundTokens = eogMeta.totalTokens ?? respText.length ?? 0;
            const truncatedMidWord = /\w$/.test(respText.trim());
            console.warn(`[ChatEngine] EOG DIAGNOSTIC (continuation) ── stopReason=eogToken`);
            console.warn(`  tokens generated: ${roundTokens}, maxTokens budget: ${genOptions.maxTokens}`);
            console.warn(`  context: ${ctxUsedNow}/${contextSize}, gpuLayers=${this._model?.gpuLayers ?? '?'}`);
            console.warn(`  last 80 chars: "${lastChars}"`);
            console.warn(`  truncated mid-word: ${truncatedMidWord}`);
            console.warn(`  metadata keys: ${Object.keys(eogMeta).join(', ')}`);
            console.warn(`  chatWrapper: ${this._chat?.chatWrapper?.wrapperName ?? 'unknown'}`);
          }
          const _contResp = result.response || '';
          const _contThink = _contResp.match(/<think>([\s\S]*?)<\/think>/) || _contResp.match(/<reasoning>([\s\S]*?)<\/reasoning>/) || _contResp.match(/<reflection>([\s\S]*?)<\/reflection>/);
          if (_contThink) {
            console.log(`[ChatEngine] ─── CONTINUATION THINKING ─── "${_contThink[1]}"`);
          }
          console.log(`[ChatEngine] ─── CONTINUATION RESPONSE ─── "${_contResp}"`);

          _sfFlush();
          _sfFlushFence();

          const newText = fullResponse.substring(roundStart);
          parsedCalls = parseToolCalls(newText);
          if (parsedCalls.length > 0) {
            const preContRepair = parsedCalls;
            const { repaired, issues } = repairToolCalls(parsedCalls, newText);
            if (repaired.length === 0 && issues.length > 0) {
              console.warn(`[ChatEngine] Continuation: all tool call(s) failed validation — feeding errors back`);
              this._chatHistory.push({
                type: 'user',
                text: `[System: Tool Validation Failed]\n${issues.join('\n')}\n\nRetry with valid tool parameters.`,
              });
              repairRetryPending = true;
              if (onStreamEvent && preContRepair.length) {
                onStreamEvent('tool-executing', preContRepair.map((c) => ({ tool: c.tool, params: c.params })));
                onStreamEvent('mcp-tool-results', preContRepair.map((c) => ({
                  tool: c.tool,
                  result: { success: false, error: issues.join('; ') },
                })));
              }
              parsedCalls = [];
            } else {
              parsedCalls = filterWebWorkspaceToolConflict(repaired);
            }
            if (options.planMode && options.agentPhase !== 'building' && parsedCalls.length > 0) {
              const { calls: planCalls, blocked } = filterPlanModeToolCalls(parsedCalls);
              if (blocked.length > 0) {
                console.log(`[ChatEngine] Plan mode (continuation) — blocked ${blocked.length} tool call(s): [${blocked.map(c => c.tool).join(', ')}]`);
                this._chatHistory.push({
                  type: 'user',
                  text: `[System: Plan mode — only read/search/git tools, create_directory for .guide/plans, and write_file/edit_file for .guide/plans/*.plan.md are allowed. Blocked: ${blocked.map(c => c.tool).join(', ')}. Continue planning with permitted tools.]`,
                });
              }
              parsedCalls = planCalls;
            }
          }

        }
        } // end prose JSON fallback path

      } else if (executeToolFn && _userAbortedGeneration) {
        console.log(`[ChatEngine] Skipping tool parse/execute — generation stopReason=${_genStopReason} (user stopped)`);
      }

      this._lastEvaluation = result.lastEvaluation;
      if (result.lastEvaluation?.cleanHistory) {
        console.log(`[ChatEngine] Applying cleanHistory from lastEvaluation: ${result.lastEvaluation.cleanHistory.length} msgs`);
        this._chatHistory = result.lastEvaluation.cleanHistory;
      }
      const stopReason = result.metadata?.stopReason || 'natural';

      _sfCatchUpVisibleProse();

      if (_sfNativeThinkActive && _sfVisibleChars === 0 && _sfNativeThinkChars > 0) {
        console.warn(`[ChatEngine] Thought-segment trap: ${_sfNativeThinkChars} chars in thought, 0 in visible chat — check Mode C + native FC interaction`);
      }
      console.log(`[ChatEngine] Generation complete. Tool calls: ${totalToolCalls}, stopReason=${stopReason}, responseLen=${fullResponse.length}, thoughtLen=${_sfNativeThinkChars}, visibleLen=${_sfVisibleChars}`);
      if (_proseLogBuf) { _logStreamDiag(`[StreamDiag] PROSE (final): ${JSON.stringify(_proseLogBuf)}`); _proseLogBuf = ''; }
      if (_thinkLogBuf) { _logStreamDiag(`[StreamDiag] THINK (final): ${JSON.stringify(_thinkLogBuf)}`); _thinkLogBuf = ''; }
      // Log visible response text to help diagnose model looping/drifting.
      // This is the text the user actually sees (tool JSON is stripped, thinking is separate).
      if (_sfVisibleChars > 0) {
        const _visPreview = fullResponse.replace(/\n/g, '\\n').slice(0, 500);
        console.log(`[ChatEngine] Visible response preview (first 500 chars): "${_visPreview}${fullResponse.length > 500 ? '...' : ''}"`);
      }
      if (_sfVisibleChars === 0 && nativeThinkFullText) {
        console.log(`[ChatEngine] No visible output — ${nativeThinkFullText.length} chars of native thinking generated`);
      }

      // Inference speed diagnostic
      const ctxUsedTokens = this._sequence?.nextTokenIndex || 0;
      const totalCtx = this._context?.contextSize || 0;
      const gpuLayers = this.modelInfo?.gpuLayers || 0;
      const totalLayers = this.modelInfo?.totalLayers || gpuLayers;
      const ctxPct = totalCtx > 0 ? Math.round((ctxUsedTokens / totalCtx) * 100) : 0;
      const totalGenElapsed = (Date.now() - genStartTime) / 1000;
      const avgTokPerSec = totalGenElapsed > 0 && genTokenCount > 0 ? (genTokenCount / totalGenElapsed).toFixed(1) : '?';
      console.log(`[ChatEngine] Inference diagnostic: ctx=${ctxUsedTokens}/${totalCtx} (${ctxPct}%), gpuLayers=${gpuLayers}/${totalLayers}, responseLen=${fullResponse.length}, thoughtLen=${_sfNativeThinkChars}, visibleLen=${_sfVisibleChars}, genTokens=${genTokenCount}, totalGenTokens=${totalGenTokens}, totalTime=${totalGenElapsed.toFixed(1)}s, avgTok/s=${avgTokPerSec}, model=${this.modelInfo?.name}`);
      // Memory monitoring: check VRAM/RAM pressure after generation
      if (this.gpuPreference !== 'cpu') {
        try {
          const vramState = await this._llama.getVramState();
          const vramFreeNow = vramState?.free || 0;
          const vramTotalNow = vramState?.total || 0;
          const vramUsedPct = vramTotalNow > 0 ? Math.round(((vramTotalNow - vramFreeNow) / vramTotalNow) * 100) : 0;
          if (vramUsedPct > 90 && onStreamEvent) {
            // Rate-limit: only emit once per 5 minutes to avoid spamming the UI
            const now = Date.now();
            if (!this._lastVramWarn || (now - this._lastVramWarn) > 300000) {
              this._lastVramWarn = now;
              onStreamEvent('generation-warning', {
                message: `VRAM is ${vramUsedPct}% full — generation may slow down or fail`,
                suggestion: 'Try reducing context size or GPU layers in settings.',
              });
            }
          }
          console.log(`[ChatEngine] Memory post-gen: vramUsed=${vramUsedPct}%, vramFree=${(vramFreeNow/1e9).toFixed(2)}GB, ramFree=${(os.freemem()/1e9).toFixed(2)}GB`);
        } catch (e) { console.warn('[ChatEngine] Memory post-gen check failed:', e.message); }
      }

      // Emit error only when neither visible response nor native thinking was produced
      const hadVisibleOutput = !!fullResponse.trim() || _sfVisibleChars > 0;
      const hadThinkingOutput = _sfNativeThinkChars > 0;
      if (!hadVisibleOutput && !hadThinkingOutput && stopReason !== 'cancelled' && stopReason !== 'abort' && onStreamEvent) {
        console.warn(`[ChatEngine] Empty response warning: stopReason=${stopReason}, contextTokens=${contextTokens}, thoughtLen=0, visibleLen=${_sfVisibleChars}`);
        onStreamEvent('generation-error', {
          message: 'Model produced no output',
          suggestion: contextTokens < 4096
            ? `Context window is only ${contextTokens.toLocaleString()} tokens — too small for this model's tool prompt. Try a different model, increase context size in settings, or start a new session.`
            : 'The model may have encountered an internal error. Try again or start a new session.',
        });
      }

      visibleResponse = stripToolCallText(fullResponse);
      if (_sfHadAgentFenceRoute || _sfFileRoutedChars > 0) {
        visibleResponse = _sfStripPlainCodeFencesFromProse(visibleResponse);
      }
      console.log(`[ChatEngine] chat() returning: textLen=${visibleResponse.length}, stopReason=${stopReason}, toolCalls=${totalToolCalls}`);
      if (onComplete) onComplete(fullResponse);
      _chatStopReason = stopReason;
      return { text: visibleResponse, stopReason, toolCallCount: totalToolCalls };
    } catch (err) {
      const errName = err?.name ?? 'Error';
      const errMsg = String(err?.message ?? err ?? '');
      console.error(`[ChatEngine] chat() CATCH: ${errName}: ${errMsg || '(no message)'}`);
      const isAbort =
        err?.name === 'AbortError' ||
        this._cancelRequested ||
        this._abortController?.signal?.aborted ||
        /eval has failed|checkpoint max position mismatch|inconsistent sequence positions/i.test(errMsg) ||
        (!errMsg && (this._cancelRequested || this._abortController?.signal?.aborted));
      if (isAbort) {
        console.log('[ChatEngine] chat() returning cancelled');
        _chatStopReason = 'cancelled';
        return { text: stripToolCallText(fullResponse), stopReason: 'cancelled', toolCallCount: totalToolCalls };
      }
      const isContextFull = /context shift strategy|did not return a history that fits|context size is too small/i.test(errMsg);
      const displayMsg = errMsg || 'Unknown generation error';
      if (onStreamEvent) {
        onStreamEvent('generation-error', {
          message: isContextFull
            ? 'Context full — start a new session or reduce tool-heavy steps'
            : `Generation failed: ${displayMsg}`,
          suggestion: isContextFull
            ? 'The conversation and tool results exceeded the model context window even after compression. Start a new session or open a smaller project task.'
            : 'Try again, start a new session, or check the backend log for details.',
        });
      }
      throw err;
    } finally {
      console.log('[ChatEngine] chat() FINALLY: abortController cleared');
      if (
        this._pendingUserMessage
        && (_chatStopReason === 'cancelled' || _chatStopReason === 'abort')
      ) {
        console.warn('[ChatEngine] Clearing undelivered _pendingUserMessage after cancelled chat()');
        this._pendingUserMessage = null;
      }
      this._abortController = null;
      this._cancelRequested = false;
      this._toolExecFingerprints = [];
    }
  }

  cancelGeneration(reason) {
    console.log(`[ChatEngine] cancelGeneration called: reason=${reason || 'cancelled'}`);
    streamTrace.trace('stream', 'cancel-generation', {
      reason: reason || 'cancelled',
      abortActive: !!this._abortController,
      activeChatPromise: !!this._activeChatPromise,
      cancelled: this._cancelRequested,
    });
    this._cancelRequested = true;
    if (this._abortController) {
      this._abortController.abort(reason || 'cancelled');
    }
  }

  isCancelled() {
    return !!(this._cancelRequested || this._abortController?.signal?.aborted);
  }

  /**
   * Revert the backend context to match a truncated frontend message array.
   * Called when the user clicks the pencil edit submit or a checkpoint restore button.
   * Rebuilds _chatHistory from the provided messages, preserving the system prompt entry.
   * @param {Array<{role:string, content:string}>} messages - truncated chatMessages from frontend
   */
  revertContext(messages) {
    if (!this._chatHistory?.length) return;
    // Cancel any in-flight generation before mutating history
    if (this._abortController) {
      this._abortController.abort('context_revert');
    }
    const systemEntry = this._chatHistory[0]; // preserve system prompt + tool definitions
    const newHistory = systemEntry ? [{ ...systemEntry }] : [{ type: 'system', text: SYSTEM_PROMPT }];
    for (const msg of (messages || [])) {
      if (!msg?.role || msg.content == null) continue;
      if (msg.role === 'user') {
        newHistory.push({ type: 'user', text: String(msg.content) });
      } else if (msg.role === 'assistant') {
        newHistory.push({ type: 'model', response: [String(msg.content)] });
      }
    }
    this._chatHistory = newHistory;
    this._lastEvaluation = null; // force full context rebuild on next generation
    // Clear the sequence's KV cache so stale tokens don't contaminate the rebuilt history.
    // resetSession() does the same thing — revertContext must match that behaviour.
    if (this._sequence) {
      try { this._sequence.clearHistory(); } catch (_) {}
    }
    console.log(`[ChatEngine] Context reverted: rebuilt from ${messages?.length || 0} messages → ${newHistory.length - 1} history entries (system entry preserved, KV cache cleared)`);
  }

  /**
   * Spawn a focused sub-agent using the same loaded model with a fresh context.
   * Sub-agents run SEQUENTIALLY (local hardware can't run two models in parallel).
   * The sub-context is disposed immediately after the task completes to free VRAM.
   * @param {string} task - the sub-task description
   * @param {object} [opts] - { contextSize, temperature, maxTokens, toolPrompt, executeToolFn }
   */
  async spawnSubAgent(task, opts = {}) {
    if (!this._model) throw new Error('No model loaded — cannot spawn sub-agent');
    console.log(`[ChatEngine] Sub-agent spawning: "${String(task)}"`);
    const llamaCppPath = this._getNodeLlamaCppPath();
    const { LlamaChat } = await import(pathToFileURL(llamaCppPath).href);
    // Sub-agent context is at most half the main context, with a runtime floor of
    // MIN_CONTEXT_FLOOR. No hardcoded fallback values — if the main context is not
    // available, the sub-agent allocation derives from MIN_CONTEXT_FLOOR alone so
    // the same code works on a 4 GB laptop and a 128 GB workstation (Rule 9).
    const mainCtx = this._context?.contextSize || MIN_CONTEXT_FLOOR;
    const halfMain = Math.floor(mainCtx / 2);
    const requested = (Number.isFinite(opts.contextSize) && opts.contextSize > 0) ? opts.contextSize : halfMain;
    const subCtxSize = Math.max(MIN_CONTEXT_FLOOR, Math.min(requested, halfMain));
    let subContext = null;
    try {
      subContext = await this._model.createContext({ contextSize: subCtxSize });
      const subSequence = subContext.getSequence();
      const subChat = new LlamaChat({
        contextSequence: subSequence,
        chatWrapper: this._chatWrapper || 'auto',
      });
      const subHistory = [
        { type: 'system', text: `You are a focused sub-agent. Complete the task below fully and return your results in clear text.\n\nTask: ${task}` },
        { type: 'user', text: task },
      ];
      let subResponse = '';
      const subGenOptions = {
        temperature: opts.temperature ?? 0.3,
        signal: this._abortController?.signal,   // cancel sub-agent when main cancel fires
        stopOnAbortSignal: true,
        onTextChunk: (chunk) => { subResponse += chunk; },
      };
      if (opts.toolPrompt && opts.executeToolFn) {
        subHistory[0].text += `\n\n${opts.toolPrompt}`;
      }
      const result = await subChat.generateResponse(subHistory, subGenOptions);
      subResponse = result?.response || subResponse;
      console.log(`[ChatEngine] Sub-agent completed: ${subResponse.length} chars`);
      return { success: true, result: subResponse };
    } catch (err) {
      console.error(`[ChatEngine] Sub-agent failed: ${err.message}`);
      return { success: false, error: err.message };
    } finally {
      try { subContext?.dispose(); } catch (_) {}
    }
  }

  /**
   * Inject a user message into the ongoing tool call loop.
   * The message will be prepended to the next continuation's tool results
   * so the model sees it immediately and can adjust its behavior.
   */
  injectUserMessage(text) {
    console.log(`[ChatEngine] injectUserMessage: text=${String(text)}`);
    if (!this._abortController) {
      console.warn('[ChatEngine] injectUserMessage rejected: no active generation');
      return { delivered: false };
    }
    this._pendingUserMessage = text;
    this.cancelGeneration('user-interrupt');
    return { delivered: true };
  }

  async resetSession() {
    console.log('[ChatEngine] resetSession START');
    if (this._loadPromise) {
      console.log('[ChatEngine] resetSession: awaiting in-flight model load');
      try { await this._loadPromise; } catch (_) { /* load failed */ }
    }
    if (this._loadState === 'loading' || this._loadState === 'disposing') {
      console.warn('[ChatEngine] resetSession skipped — model load in progress');
      return;
    }
    this._sessionId++;
    this._chatHistory = [{ type: 'system', text: SYSTEM_PROMPT }];
    this._lastEvaluation = null;
    if (this._sequence) {
      try { this._sequence.clearHistory(); } catch (e) { console.warn('[ChatEngine] resetSession clearHistory failed:', e.message); }
    }
    console.log(`[ChatEngine] resetSession DONE: newSessionId=${this._sessionId}`);
  }

  /**
   * Swap the chat wrapper on the fly without reloading the model.
   * Resets conversation history so the new wrapper context is clean.
   * Modes: 'C' = ThinkingOpen (prefix injection), 'B' = raw Jinja (no prefix),
   *        'auto' = node-llama-cpp auto resolver, 'off' = Jinja enable_thinking=false
   */
  async setWrapperMode(mode) {
    console.log(`[ChatEngine] setWrapperMode START mode=${mode} ready=${this.isReady} currentMode=${this._currentThinkingMode}`);
    if (!this.isReady || !this._sequence) throw new Error('No model loaded');
    if (!this._LlamaChat) throw new Error('LlamaChat class not available — model may need to be reloaded once');
    const template = this._ggufChatTemplate;
    let chatWrapperOpt = 'auto';
    if (template && mode !== 'auto') {
      const jinjaOpts = {
        template,
        tokenizer: this._model.tokenizer,
        additionalRenderParameters: { ...this._chatTemplateKwargs, enable_thinking: mode !== 'off' },
        segments: { thoughtTemplate: '<think>{{content}}</think>', reopenThoughtAfterFunctionCalls: false },
      };
      try {
        if (mode === 'C' && this._ThinkingOpenJinjaChatWrapper) {
          chatWrapperOpt = new this._ThinkingOpenJinjaChatWrapper(jinjaOpts);
        } else if ((mode === 'B' || mode === 'off') && this._JinjaTemplateChatWrapper) {
          chatWrapperOpt = new this._JinjaTemplateChatWrapper(jinjaOpts);
        }
      } catch (err) {
        console.warn(`[ChatEngine] setWrapperMode: wrapper creation failed for mode=${mode}: ${err.message}`);
        chatWrapperOpt = 'auto';
      }
    }
    this._chatWrapper = chatWrapperOpt;
    this._chat = new this._LlamaChat({ contextSequence: this._sequence, chatWrapper: chatWrapperOpt });
    this._chatHistory = [{ type: 'system', text: SYSTEM_PROMPT }];
    this._lastEvaluation = null;
    this._sessionId++;
    this._currentThinkingMode = mode;
    if (this._sequence) {
      try { this._sequence.clearHistory(); } catch (_) {}
    }
    console.log(`[ChatEngine] setWrapperMode DONE: mode=${mode}, wrapper=${chatWrapperOpt === 'auto' ? 'auto' : chatWrapperOpt.wrapperName ?? '?'}, sessionId=${this._sessionId}`);
    return { success: true, mode, wrapper: chatWrapperOpt === 'auto' ? 'auto' : (chatWrapperOpt.wrapperName ?? mode) };
  }

  getStatus() {
    const status = {
      isReady: this.isReady,
      isLoading: this.isLoading,
      loadState: this._loadState,
      modelInfo: this.modelInfo,
      currentModelPath: this.currentModelPath,
      gpuPreference: this.gpuPreference,
    };
    console.log(`[ChatEngine] getStatus: ready=${status.isReady}, loading=${status.isLoading}`);
    return status;
  }

  /**
   * One-shot text completion for inline/Tab completion — does not mutate chat history.
   * @param {string} prompt
   * @param {{ maxTokens?: number, temperature?: number }} [options]
   * @returns {Promise<{ text: string }>}
   */
  async completeOnce(prompt, options = {}) {
    if (!this.isReady || !this._model || !prompt) return { text: '' };
    const maxTokens = options.maxTokens ?? 64;
    const temperature = options.temperature ?? 0.2;
    let subContext = null;
    try {
      const llamaCppPath = this._getNodeLlamaCppPath();
      const { LlamaChat } = await import(pathToFileURL(llamaCppPath).href);
      const subCtxSize = Math.min(2048, Math.max(512, Math.ceil(prompt.length / 3) + maxTokens + 128));
      subContext = await this._model.createContext({
        contextSize: { min: 256, max: subCtxSize },
        failedCreationRemedy: { retries: 2, autoContextSizeShrink: 0.5 },
        gpuLayers: 0,
      });
      const subSequence = subContext.getSequence();
      const subChat = new LlamaChat({
        contextSequence: subSequence,
        chatWrapper: this._chatWrapper || 'auto',
      });
      let text = '';
      const result = await subChat.generateResponse([{ type: 'user', text: prompt }], {
        temperature,
        maxTokens,
        onTextChunk: (chunk) => { text += chunk; },
      });
      return { text: (result?.response || text).trim() };
    } catch (err) {
      console.warn('[ChatEngine] completeOnce failed:', err.message);
      return { text: '' };
    } finally {
      try { subContext?.dispose(); } catch (_) {}
    }
  }

  async getGPUInfo() {
    // Plan 8 instrumentation — log inter-call delta so the next session reveals
    // any caller that runs more often than the documented StatusBar 60s cadence.
    // No retry, no rate-limit, no behavior change. Diagnostic-only.
    try {
      const _now = Date.now();
      const _delta = this._lastGetGpuInfoTs ? (_now - this._lastGetGpuInfoTs) : 0;
      this._lastGetGpuInfoTs = _now;
      console.log(`[ChatEngine] getGPUInfo START (delta=${_delta}ms since last)`);
    } catch (_) { console.log('[ChatEngine] getGPUInfo START'); }
    try {
      const { execFile } = require('child_process');
      const { promisify } = require('util');
      const execFileAsync = promisify(execFile);
      const { stdout } = await execFileAsync(
        'nvidia-smi',
        ['--query-gpu=name,memory.total,memory.used,memory.free,utilization.gpu,temperature.gpu', '--format=csv,noheader,nounits'],
        { timeout: 5000 },
      );
      const [name, memTotal, memUsed, memFree, utilGpu, temp] = stdout.trim().split(',').map(s => s.trim());
      console.log(`[ChatEngine] getGPUInfo: name=${name}, memTotal=${memTotal}, memUsed=${memUsed}, memFree=${memFree}`);
      const info = {
        name,
        memoryTotal: parseFloat(memTotal),
        memoryUsed: parseFloat(memUsed),
        memoryFree: parseFloat(memFree),
        gpuUtilization: parseFloat(utilGpu),
        temperature: parseFloat(temp),
      };
      this._cachedGpuInfo = info;
      return info;
    } catch (e) {
      if (this._cachedGpuInfo) {
        console.log(`[ChatEngine] getGPUInfo failed (${e.message}) — returning cached reading`);
        return this._cachedGpuInfo;
      }
      console.warn(`[ChatEngine] getGPUInfo failed: ${e.message}`);
      return { name: 'Unknown', memoryTotal: 0, memoryUsed: 0, memoryFree: 0, gpuUtilization: 0, temperature: 0 };
    }
  }

  async dispose() {
    console.log('[ChatEngine] dispose START');
    this._loadState = 'disposing';
    await this._dispose();
    this.isReady = false;
    this.isLoading = false;
    this._loadState = 'idle';
    this.modelInfo = null;
    this.currentModelPath = null;
    this.emit('status', { state: 'idle', message: 'Model unloaded' });
    console.log('[ChatEngine] dispose DONE');
  }

  async _dispose() {
    console.log('[ChatEngine] _dispose START');
    try { await visionServer.stop(); } catch (e) { console.warn('[ChatEngine] _dispose visionServer.stop failed:', e.message); }
    try { if (this._sequence) this._sequence.dispose(); } catch (e) { console.warn('[ChatEngine] _dispose sequence.dispose failed:', e.message); }
    try { if (this._context) await this._context.dispose(); } catch (e) { console.warn('[ChatEngine] _dispose context.dispose failed:', e.message); }
    try { if (this._model) await this._model.dispose(); } catch (e) { console.warn('[ChatEngine] _dispose model.dispose failed:', e.message); }
    this._sequence = null;
    this._context = null;
    this._model = null;
    this._chat = null;
    this._chatHistory = [];
    this._lastEvaluation = null;
    console.log('[ChatEngine] _dispose DONE');
  }

  /**
   * Token count of the fully rendered prompt — same check node-llama-cpp uses after shift.
   */
  _measureRenderedTokens({ chatHistory, tokenizer, chatWrapper, functions, documentFunctionParams }) {
    const fcFunctions = functions ?? this._shiftMeasureFunctions;
    const fcDocParams = documentFunctionParams ?? this._shiftMeasureDocumentFunctionParams;
    const wrapper = chatWrapper || this._chat?.chatWrapper;
    if (!wrapper?.generateContextState || !tokenizer) {
      let sum = 0;
      for (const item of chatHistory) {
        const text = item.text != null ? String(item.text)
          : (item.response ? item.response.map((r) => (typeof r === 'string' ? r : JSON.stringify(r))).join('') : '');
        try { sum += tokenizer.tokenize(text, false).length; } catch { sum += Math.ceil(text.length / 3); }
      }
      return sum;
    }
    try {
      const { contextText } = wrapper.generateContextState({
        chatHistory,
        availableFunctions: fcFunctions,
        documentFunctionParams: fcDocParams,
      });
      return contextText.tokenize(tokenizer).length;
    } catch (e) {
      console.warn('[ChatEngine] _measureRenderedTokens fallback:', e.message);
      let sum = 0;
      for (const item of chatHistory) {
        const text = item.text != null ? String(item.text) : '';
        try { sum += tokenizer.tokenize(text, false).length; } catch { sum += Math.ceil(text.length / 3); }
      }
      return sum;
    }
  }

  _contextShiftSize(contextSize) {
    return Math.max(1, Math.floor((contextSize || 0) / 10));
  }

  /** Extract text content from a chat history item (handles both .text and .response formats). */
  _getHistoryItemText(item) {
    if (item.text != null) return String(item.text);
    if (item.response) {
      return item.response.map(r => typeof r === 'string' ? r : JSON.stringify(r)).join('');
    }
    return '';
  }

  _insertContextRotationNotice(history, droppedCount, pinnedUserText = '', progressSummary = null) {
    if (!droppedCount || droppedCount <= 0) return history;
    const scratchRel = this._projectPath ? '.guide-scratch/context-state.md' : null;

    // Replace any existing rotation notice — consecutive shifts must update, not skip
    const copy = history.slice();
    const existingIdx = copy.findIndex((m) => m.type === 'user' && RE_CONTEXT_ROTATED.test(String(m.text || '')));
    if (existingIdx >= 0) copy.splice(existingIdx, 1);

    const taskLine = pinnedUserText
      ? `TASK: "${pinnedUserText.slice(0, 300)}${pinnedUserText.length > 300 ? '...' : ''}"`
      : 'TASK: (not found)';
    const progressLine = progressSummary
      ? `Progress summary:\n${progressSummary}`
      : 'Progress summary: (generating...)';

    const text = `[System: Session memory condensed] ${droppedCount} earlier turn(s) summarized.\n${taskLine}\n${progressLine}\nDo not mention context limits or rotation to the user.\n`;

    copy.splice(Math.max(1, copy.length - 1), 0, { type: 'user', text });
    return copy;
  }

  /**
   * Summarize dropped context using the same loaded model via a sub-context.
   * Pattern: identical to spawnSubAgent — createContext on the same model weights,
   * generate a short summary, dispose the sub-context immediately.
   * Returns summary string on success, null on any failure or skip.
   */
  async _summarizeDroppedContext(droppedItems, taskHint, enabled) {
    console.log(`[ChatEngine] Summarizer ENTER: enabled=${enabled}, droppedItems=${droppedItems?.length ?? 0}, hasModel=${!!this._model}`);
    if (!enabled) { console.log('[ChatEngine] Summarizer SKIP: disabled'); return null; }
    if (!droppedItems || droppedItems.length === 0) { console.log('[ChatEngine] Summarizer SKIP: no dropped items'); return null; }
    if (!this._model) { console.log('[ChatEngine] Summarizer SKIP: no model'); return null; }

    const mainCtx = this._context?.contextSize || 0;
    if (mainCtx < 2048) {
      console.log('[ChatEngine] Summarizer SKIP: main context too small');
      return null;
    }

    // B1: VRAM gate — if insufficient free VRAM for a GPU sub-context,
    // try CPU-only sub-context (gpuLayers: 0) before falling to deterministic.
    // On a 4GB GPU with a 9B model, GPU sub-context fails but CPU works — it's
    // just slower. This produces real summaries instead of garbage.
    let _summarizerUseCpu = false;
    if (this._llama && this.gpuPreference !== 'cpu') {
      try {
        const vramState = await this._llama.getVramState();
        const vramFree = vramState?.free || 0;
        const MIN_SUB_CONTEXT_VRAM = 64 * 1024 * 1024; // 64 MB
        if (vramFree < MIN_SUB_CONTEXT_VRAM) {
          console.log(`[ChatEngine] Summarizer: insufficient VRAM for GPU sub-context (${Math.round(vramFree / 1024 / 1024)}MB free), trying CPU-only sub-context`);
          _summarizerUseCpu = true;
        }
      } catch (e) {
        console.warn('[ChatEngine] Summarizer VRAM gate check failed:', e.message);
      }
    }

    const subCtxSize = Math.min(4096, Math.max(1024, Math.floor(mainCtx * 0.1)));
    const inputCharCap = Math.max(600, (subCtxSize - 500) * 3);
    let subContext = null;

    try {
      const llamaCppPath = this._getNodeLlamaCppPath();
      const { LlamaChat } = await import(pathToFileURL(llamaCppPath).href);

      subContext = await this._model.createContext({
        contextSize: { min: 256, max: subCtxSize },
        failedCreationRemedy: { retries: 4, autoContextSizeShrink: 0.4 },
        ...(_summarizerUseCpu ? { gpuLayers: 0 } : {}),
      });
      const subSequence = subContext.getSequence();
      const subChat = new LlamaChat({
        contextSequence: subSequence,
        chatWrapper: this._chatWrapper || 'auto',
      });

      // Build compact text from dropped items, capped to inputCharCap
      let inputText = '';
      for (const item of droppedItems) {
        const role = item.type === 'user' ? 'User' : item.type === 'model' ? 'Assistant' : 'System';
        const text = this._getHistoryItemText(item);
        const line = `[${role}] ${text.slice(0, 600)}\n`;
        if (inputText.length + line.length > inputCharCap) {
          inputText += `[... ${droppedItems.length} items total, truncated]\n`;
          break;
        }
        inputText += line;
      }

      const systemPrompt = `You are a task continuity assistant. Summarize the following conversation segment using concise bullet points. Focus on: tools called, files created or modified, URLs visited, and current task progress state. Be specific with paths and URLs. No preamble. Start immediately with bullet points.`;
      const userPrompt = taskHint
        ? `Task: ${taskHint.slice(0, 300)}\n\nConversation to summarize:\n${inputText}`
        : `Conversation to summarize:\n${inputText}`;

      const subHistory = [
        { type: 'system', text: systemPrompt },
        { type: 'user', text: userPrompt },
      ];

      let summary = '';
      const result = await subChat.generateResponse(subHistory, {
        temperature: 0.1,
        maxTokens: 250,
        signal: this._abortController?.signal,
        stopOnAbortSignal: true,
        onTextChunk: (chunk) => { summary += chunk; },
      });
      summary = (result?.response || summary).trim();
      console.log(`[ChatEngine] Summarizer DONE: generated ${summary.length} chars from ${droppedItems.length} dropped items`);
      return summary || null;
    } catch (err) {
      console.warn(`[ChatEngine] Summarizer FAILED: ${err.message}`);
      // If VRAM is the issue, try the dispose-and-recreate approach
      if (/VRAM|memory|context size|failed to create|allocation/i.test(err.message)) {
        console.log('[ChatEngine] Summarizer: attempting VRAM reclaim (dispose main context → summarize → recreate)');
        const reclaimResult = await this._summarizeWithVramReclaim(droppedItems, taskHint);
        if (reclaimResult) return reclaimResult;
      }
      return this._extractDeterministicSummary(droppedItems);
    } finally {
      try { subContext?.dispose(); } catch (_) {}
    }
  }

  /**
   * Summarize dropped context by creating a small sub-context alongside the
   * main context. Unlike the old dispose-and-recreate approach, this method
   * NEVER disposes the main context, so there is no crash path that leaves
   * _chat as null.
   *
   * If sub-context creation fails (VRAM too tight), falls back to
   * _extractDeterministicSummary which requires zero VRAM.
   *
   * B3: LlamaChat is imported at the TOP of this method so it's available
   * in both try and catch blocks (fixes the ReferenceError crash).
   */
  async _summarizeWithVramReclaim(droppedItems, taskHint) {
    if (!this._baseCtxOpts || !this._model) return null;
    console.log('[ChatEngine] Summarizer fallback ENTER (non-destructive, no main context disposal)');

    // B3: Import LlamaChat at method scope — available in both try and catch
    const llamaCppPath = this._getNodeLlamaCppPath();
    let LlamaChat;
    try {
      ({ LlamaChat } = await import(pathToFileURL(llamaCppPath).href));
    } catch (importErr) {
      console.warn(`[ChatEngine] Summarizer fallback: LlamaChat import failed: ${importErr.message}`);
      return this._extractDeterministicSummary(droppedItems);
    }

    let subContext = null;
    try {
      // Try creating a small sub-context with aggressive shrink retries.
      // This may succeed on GPUs with enough leftover VRAM after the main context.
      // On 4GB GPUs it will likely fail — that's fine, we fall back gracefully.
      const subCtxSize = Math.min(4096, Math.max(1024, Math.floor((this._baseCtxOpts.contextSize || 4096) * 0.1)));
      subContext = await this._model.createContext({
        contextSize: { min: 256, max: subCtxSize },
        failedCreationRemedy: { retries: 6, autoContextSizeShrink: 0.4 },
      });
      const subSequence = subContext.getSequence();
      const subChat = new LlamaChat({
        contextSequence: subSequence,
        chatWrapper: this._chatWrapper || 'auto',
      });

      // Build compact text from dropped items (same logic as _summarizeDroppedContext)
      const inputCharCap = Math.max(600, (subCtxSize - 500) * 3);
      let inputText = '';
      for (const item of droppedItems) {
        const role = item.type === 'user' ? 'User' : item.type === 'model' ? 'Assistant' : 'System';
        const text = this._getHistoryItemText(item);
        const line = `[${role}] ${text.slice(0, 600)}\n`;
        if (inputText.length + line.length > inputCharCap) {
          inputText += `[... ${droppedItems.length} items total, truncated]\n`;
          break;
        }
        inputText += line;
      }

      const systemPrompt = `You are a task continuity assistant. Summarize the following conversation segment using concise bullet points. Focus on: tools called, files created or modified, URLs visited, and current task progress state. Be specific with paths and URLs. No preamble. Start immediately with bullet points.`;
      const userPrompt = taskHint
        ? `Task: ${taskHint.slice(0, 300)}\n\nConversation to summarize:\n${inputText}`
        : `Conversation to summarize:\n${inputText}`;

      const subHistory = [
        { type: 'system', text: systemPrompt },
        { type: 'user', text: userPrompt },
      ];

      let summary = '';
      await subChat.generateResponse(subHistory, {
        temperature: 0.1,
        maxTokens: 250,
        signal: this._abortController?.signal,
        stopOnAbortSignal: true,
        onTextChunk: (chunk) => { summary += chunk; },
      });
      summary = summary.trim();
      console.log(`[ChatEngine] Summarizer fallback DONE: ${summary.length} chars from ${droppedItems.length} items`);
      return summary || null;
    } catch (err) {
      console.warn(`[ChatEngine] Summarizer fallback FAILED: ${err.message}`);
      return this._extractDeterministicSummary(droppedItems);
    } finally {
      try { subContext?.dispose(); } catch (_) {}
    }
  }

  _extractDeterministicSummary(droppedItems, taskHint = '') {
    if (!droppedItems || droppedItems.length === 0) return null;

    const done = new Set();
    const browserLines = [];
    const stateLines = [];
    const userSnippets = [];
    let lastUrl = '';
    let lastClickLabel = '';

    const _pushDone = (line) => { if (line && !done.has(line)) { done.add(line); } };

    const _parseToolResultLine = (toolLine) => {
      const colon = toolLine.indexOf(':');
      if (colon < 0) return;
      const toolName = toolLine.slice(0, colon).trim();
      const body = toolLine.slice(colon + 1).trim();
      let parsed = null;
      const jsonStart = body.indexOf('{');
      if (jsonStart >= 0) {
        try { parsed = JSON.parse(body.slice(jsonStart)); } catch { parsed = null; }
      } else {
        try { parsed = JSON.parse(body); } catch { parsed = null; }
      }

      if (/^browser_/.test(toolName)) {
        const url = parsed?.url || (body.match(/URL[=:]\s*(\S+)/i) || [])[1] || '';
        if (url) lastUrl = url;
        const snap = parsed?.text || parsed?.snapshot || '';
        if (snap && browserLines.length < 3) {
          const refs = (snap.match(/\[ref=\d+\][^\n]*/g) || []).slice(0, 12);
          if (refs.length) browserLines.push(refs.join('\n'));
          const pageText = snap.split('Page text:')[1];
          if (pageText) browserLines.push(pageText.trim().slice(0, 2000));
        }
        if (toolName === 'browser_click' && parsed?.clicked) {
          lastClickLabel = String(parsed.clicked).slice(0, 120);
        }
        _pushDone(`${toolName}${url ? ` @ ${url}` : ''}${lastClickLabel && toolName === 'browser_click' ? ` → "${lastClickLabel}"` : ''}`);
        return;
      }

      if (toolName === 'run_command') {
        const cmd = parsed?.command || parsed?.cmd || body.slice(0, 120);
        _pushDone(`run_command: ${cmd}`);
        return;
      }
      if (/^write_file|edit_file|append_to_file|read_file$/.test(toolName)) {
        const fp = parsed?.filePath || parsed?.path || (body.match(/"(?:filePath|path)"\s*:\s*"([^"]+)"/) || [])[1];
        if (!fp) {
          if (toolName === 'write_file' || toolName === 'read_file') _pushDone(toolName);
          return;
        }
        if (toolName === 'write_file') {
          _pushDone(`write_file: ${fp} (completed on disk — do not rewrite unless user asked for changes)`);
        } else if (toolName === 'read_file') {
          const totalLines = parsed?.totalLines
            ?? (() => { const m = body.match(/totalLines=(\d+)/); return m ? Number(m[1]) : null; })();
          _pushDone(`read_file: ${fp}${totalLines != null ? ` (${totalLines} lines on disk)` : ' (full file on disk)'}`);
        } else {
          _pushDone(`${toolName}: ${fp}`);
        }
        return;
      }
      if (toolName === 'write_todos' || toolName === 'update_todo') {
        stateLines.push(body.slice(0, 300));
        _pushDone(`${toolName}`);
      }
    };

    for (const item of droppedItems) {
      const text = this._getHistoryItemText(item).trim();
      if (!text) continue;

      if (item.type === 'user') {
        if (RE_TOOL_OR_SYSTEM_INJECT.test(text) || RE_CONTEXT_ROTATED.test(text)) {
          const lines = text.split('\n');
          for (const line of lines) {
            if (/^(browser_|read_file|write_file|run_command)/.test(line)) _parseToolResultLine(line);
            else if (line.includes(':') && /^(browser_|read_file|write_file|run_command)/.test(line.split(':')[0])) {
              _parseToolResultLine(line);
            }
          }
          continue;
        }
        if (!/^\[System:/i.test(text) && userSnippets.length < 3) {
          userSnippets.push(_sanitizeFileSnippetText(text).slice(0, 500));
        }
        continue;
      }

      if (item.type === 'model') {
        const toolNames = text.match(/"(?:tool|name)"\s*:\s*"([^"]+)"/g);
        const filePaths = text.match(/"(?:filePath|path)"\s*:\s*"([^"]+)"/g);
        if (toolNames) {
          const names = [...new Set(toolNames.map(m => m.replace(/"(?:tool|name)"\s*:\s*"/, '').replace(/"$/, '')))];
          const paths = filePaths ? [...new Set(filePaths.map(m => m.replace(/"(?:filePath|path)"\s*:\s*"/, '').replace(/"$/, '')))] : [];
          _pushDone(paths.length ? `${names.join(', ')} → ${paths.join(', ')}` : names.join(', '));
        }
      }
    }

    const sections = [];
    const sanitizedHint = taskHint ? _sanitizeFileSnippetText(taskHint) : '';
    if (sanitizedHint) sections.push(`TASK:\n${sanitizedHint.slice(0, 400)}`);
    else if (userSnippets[0]) sections.push(`TASK:\n${userSnippets[0].slice(0, 400)}`);
    if (done.size) sections.push(`DONE:\n${[...done].slice(0, 20).join('\n')}`);
    if (lastUrl || browserLines.length) {
      const browserBlock = [
        lastUrl ? `Last URL: ${lastUrl}` : '',
        lastClickLabel ? `Last click: ${lastClickLabel}` : '',
        ...browserLines,
      ].filter(Boolean).join('\n');
      sections.push(`BROWSER:\n${browserBlock.slice(0, 4000)}`);
    }
    if (stateLines.length) sections.push(`STATE:\n${stateLines.join('\n').slice(0, 600)}`);
    if (userSnippets.length > 1) sections.push(`RECENT USER:\n${userSnippets.slice(-2).join('\n---\n')}`);
    const nextStep = lastUrl
      ? 'NEXT: continue on the current page (browser_snapshot if you need fresh refs).'
      : (done.size ? 'NEXT: continue the active task; use a tool only if more work is needed.' : 'NEXT: resume work on the user task.');
    sections.push(nextStep);

    const summary = sections.join('\n\n');
    console.log(`[ChatEngine] Summarizer FALLBACK: ${sections.length} sections from ${droppedItems.length} dropped items`);
    console.log(`[ChatEngine] Summarizer FALLBACK content:\n${summary}`);
    return summary || null;
  }

  _writeContextStateFile({ chatHistory, keptIndices, getItemText, used, budget }) {
    try {
      const scratchDir = this._projectPath ? path.join(this._projectPath, '.guide-scratch') : null;
      if (!scratchDir) return;
      fs.mkdirSync(scratchDir, { recursive: true });
      const stateFile = path.join(scratchDir, 'context-state.md');
      const droppedItems = [];
      const keptItems = [];
      for (let i = 1; i <= chatHistory.length - 2; i++) {
        const item = chatHistory[i];
        const text = getItemText(item);
        const role = item.type || 'unknown';
        const line = `[${role}] ${text.slice(0, 500)}${text.length > 500 ? '...' : ''}`;
        if (keptIndices.has(i)) keptItems.push(line);
        else droppedItems.push(line);
      }
      const stateContent = [
        '# Context State',
        `Updated: ${new Date().toISOString()}`,
        `Context: ${used}/${budget} tokens (estimate)`,
        '',
        '## Current Conversation (in context)',
        ...keptItems,
        '',
        '## Dropped Conversation (shifted out)',
        ...droppedItems,
      ].join('\n');
      fs.writeFileSync(stateFile, stateContent, 'utf8');
      console.log(`[ChatEngine] Wrote context recovery file: ${stateFile} (${droppedItems.length} dropped, ${keptItems.length} kept)`);
    } catch (e) {
      console.warn('[ChatEngine] Scratch write failed:', e.message);
    }
  }

  /**
   * Pre-flight: compress history when rendered size exceeds library budget (before hard failure).
   */
  async _preflightContextBeforeGenerate({ contextSize, onStreamEvent, functions, documentFunctionParams }) {
    if (!this._chat?.chatWrapper || !this._model?.tokenizer || !contextSize) return;
    const shiftSize = this._contextShiftSize(contextSize);
    const maxTokensCount = contextSize - shiftSize;
    const measured = this._measureRenderedTokens({
      chatHistory: this._chatHistory,
      tokenizer: this._model.tokenizer,
      chatWrapper: this._chat.chatWrapper,
      functions,
      documentFunctionParams,
    });
    const kvUsed = this._sequence?.nextTokenIndex || 0;
    const genRoom = contextSize - kvUsed;
    const needsShift = measured > maxTokensCount || genRoom < 1;
    streamTrace.trace('stream', 'preflightContextBeforeGenerate', {
      measured,
      maxTokensCount,
      kvUsed,
      genRoom,
      contextSize,
      needsShift,
    });
    if (!needsShift) return;

    if (this._fileContentStreamActivePath && onStreamEvent) {
      onStreamEvent('generation-warning', {
        message: 'Condensing context during active file write — stream will continue',
        suggestion: 'Older messages were summarized. File content streaming will resume.',
      });
    }

    console.log(`[ChatEngine] Context pre-flight: renderedTokens=${measured} budget=${maxTokensCount} kvUsed=${kvUsed}/${contextSize}`);
    const shifted = this._contextShiftStrategy({
      chatHistory: this._chatHistory,
      maxTokensCount,
      tokenizer: this._model.tokenizer,
      chatWrapper: this._chat.chatWrapper,
      lastShiftMetadata: this._lastEvaluation?.contextShiftMetadata,
      functions,
      documentFunctionParams,
    });
    this._chatHistory = shifted.chatHistory;
    streamTrace.trace('stream', 'preflightContextShifted', {
      droppedCount: shifted.metadata?.droppedCount || 0,
      chatHistory: this._chatHistory.map((m) => ({
        type: m.type,
        text: m.text || m.response || m,
      })),
      metadata: shifted.metadata,
    });
    if (shifted.metadata?.droppedCount > 0) {
      const { droppedItems, pinnedUserText } = shifted.metadata;
      const syncFallback = this._extractDeterministicSummary(droppedItems, pinnedUserText);
      if (syncFallback) {
        const noticeIdx = this._chatHistory.findIndex(
          (m) => m.type === 'user' && RE_CONTEXT_ROTATED.test(String(m.text || ''))
        );
        if (noticeIdx >= 0) {
          const notice = this._chatHistory[noticeIdx];
          notice.text = notice.text.replace(
            /Progress summary:[\s\S]*?(?=\nContinue the active task|\n$)/,
            `Progress summary:\n${syncFallback}\n`
          );
        }
      }
      if (onStreamEvent) {
        onStreamEvent('generation-warning', {
          message: 'Condensing context — continuing task',
          suggestion: 'Older messages were summarized. The agent will keep working.',
        });
      }

      let summary = syncFallback;
      if (this._enableContextSummarizer) {
        const gpuSummary = await this._summarizeDroppedContext(droppedItems, pinnedUserText, true);
        if (gpuSummary && gpuSummary.length > (syncFallback?.length || 0)) {
          summary = gpuSummary;
          const noticeIdx = this._chatHistory.findIndex(
            (m) => m.type === 'user' && RE_CONTEXT_ROTATED.test(String(m.text || ''))
          );
          if (noticeIdx >= 0) {
            const notice = this._chatHistory[noticeIdx];
            notice.text = notice.text.replace(
              /Progress summary:[\s\S]*?(?=\nContinue the active task|\n$)/,
              `Progress summary:\n${summary}\n`
            );
          }
        }
      }
    }
  }

  async _generateResponseSafe(genOptions, { contextSize, onStreamEvent, functions, documentFunctionParams, userMaxTokensCap = Infinity }) {
    await this._preflightContextBeforeGenerate({ contextSize, onStreamEvent, functions, documentFunctionParams });
    // Re-read KV position after pre-flight — context shift may have freed tokens.
    // genOptions.maxTokens was computed before this call and may now be stale.
    if (contextSize && this._sequence) {
      const postPreflightUsed = this._sequence.nextTokenIndex;
      const postPreflightAvail = contextSize - postPreflightUsed;
      // After preflight shifts context, MORE tokens are available. maxTokens should
      // only increase (or stay same), never decrease.
      if (genOptions.maxTokens != null && userMaxTokensCap != null) {
        const newMax = Math.max(
          genOptions.maxTokens,
          Math.min(postPreflightAvail, userMaxTokensCap)
        );
        if (newMax > genOptions.maxTokens) {
          console.log(`[ChatEngine] maxTokens increased post-preflight: ${genOptions.maxTokens} → ${newMax} (postPreflightAvail=${postPreflightAvail})`);
          genOptions.maxTokens = newMax;
        }
      }
    }
    // Cap thinking budget to 75% of maxTokens to guarantee prose response space.
    // Without this cap, thoughtTokens > maxTokens prevents thinking from starting,
    // causing the model to generate EOG immediately (thoughtLen=0, visibleLen=2).
    if (genOptions.budgets?.thoughtTokens && isFinite(genOptions.budgets.thoughtTokens)) {
      const maxThink = Math.floor(genOptions.maxTokens * 0.75);
      if (genOptions.budgets.thoughtTokens > maxThink) {
        console.log(`[ChatEngine] thoughtTokens capped: ${genOptions.budgets.thoughtTokens} → ${maxThink} (maxTokens=${genOptions.maxTokens})`);
        genOptions.budgets = { ...genOptions.budgets, thoughtTokens: maxThink };
      }
    }
    // B4: Null guard — if summarizer or any recovery path left _chat/_sequence as null,
    // throw a descriptive error instead of letting a null-deref TypeError crash the app.
    if (!this._chat || !this._sequence) {
      console.error('[ChatEngine] FATAL: _chat or _sequence is null before generateResponse');
      this.isReady = false;
      this.emit('status', { state: 'error', message: 'Chat engine context was lost during summarization. Please reload the model.' });
      throw new Error('Chat engine context was lost during summarization and could not be recovered.');
    }
    streamTrace.trace('stream', 'generateResponse-native-enter', {
      historyLen: this._chatHistory?.length,
      genOptions,
    });
    try {
      const result = await this._chat.generateResponse(this._chatHistory, genOptions);
      streamTrace.trace('stream', 'generateResponse-native-return', {
        stopReason: result?.metadata?.stopReason,
        response: result?.response,
        metadata: result?.metadata,
        functionCalls: result?.functionCalls,
      });
      return result;
    } catch (err) {
      streamTrace.trace('stream', 'generateResponse-native-error', {
        message: err?.message,
        stack: err?.stack,
      });
      const msg = err?.message || '';
      if (!/context shift strategy|did not return a history that fits|context size is too small/i.test(msg)) throw err;
      console.warn(`[ChatEngine] Context shift recovery (retry): ${msg}`);
      const shiftSize = this._contextShiftSize(contextSize);
      const maxTokensCount = contextSize - shiftSize;
      const shifted = this._contextShiftStrategy({
        chatHistory: this._chatHistory,
        maxTokensCount,
        tokenizer: this._model.tokenizer,
        chatWrapper: this._chat.chatWrapper,
        lastShiftMetadata: this._lastEvaluation?.contextShiftMetadata,
        functions,
        documentFunctionParams,
      });
      this._chatHistory = shifted.chatHistory;
      if (shifted.metadata?.droppedCount > 0) {
        if (onStreamEvent) {
          onStreamEvent('generation-warning', {
            message: 'Condensing context — generating progress summary...',
            suggestion: 'The model is summarizing dropped context so it can continue the task.',
          });
        }
        const { droppedItems, pinnedUserText } = shifted.metadata;
        const summary = await this._summarizeDroppedContext(droppedItems, pinnedUserText, this._enableContextSummarizer);
        if (summary) {
          const noticeIdx = this._chatHistory.findIndex(
            (m) => m.type === 'user' && RE_CONTEXT_ROTATED.test(String(m.text || ''))
          );
          if (noticeIdx >= 0) {
            this._chatHistory[noticeIdx].text = this._chatHistory[noticeIdx].text.replace(
              'Progress summary: (generating...)',
              `Progress summary:\n${summary}`
            );
          }
        } else {
          const noticeIdx = this._chatHistory.findIndex(
            (m) => m.type === 'user' && RE_CONTEXT_ROTATED.test(String(m.text || ''))
          );
          if (noticeIdx >= 0) {
            this._chatHistory[noticeIdx].text = this._chatHistory[noticeIdx].text.replace(
              'Progress summary: (generating...)',
              'Progress summary: (not available — context was compressed without a summary)'
            );
          }
        }
        if (onStreamEvent) {
          onStreamEvent('generation-warning', {
            message: summary ? 'Context condensed — progress summary injected' : 'Context compressed — no summary available',
            suggestion: summary ? 'The model now has a summary of earlier work and will continue from where it left off.' : 'Older messages were dropped. The model will continue based on the remaining context.',
          });
        }
      }
      return await this._chat.generateResponse(this._chatHistory, genOptions);
    }
  }

  _contextShiftStrategy({ chatHistory, maxTokensCount, tokenizer, chatWrapper, lastShiftMetadata, functions, documentFunctionParams }) {
    void lastShiftMetadata;
    if (chatHistory.length <= 2) return { chatHistory, metadata: { droppedCount: 0, droppedItems: [], pinnedUserText: '' } };

    // Tokenizer cache — avoids re-tokenizing the same items across multiple shift calls
    const _tokenCache = new Map();
    const tokenize = (text) => {
      const key = text;
      if (_tokenCache.has(key)) return _tokenCache.get(key);
      let result;
      try { result = tokenizer.tokenize(String(text || ''), false).length; }
      catch { result = Math.ceil(String(text || '').length / 3); }
      _tokenCache.set(key, result);
      return result;
    };

    const getItemText = (item) => this._getHistoryItemText(item);

    const estimateTokens = (item) => tokenize(getItemText(item)) + 10;

    // maxTokensCount is already contextSize - contextShiftSize (library reserves ~10% for generation)
    const budget = maxTokensCount;
    const systemItem = chatHistory[0];
    const lastItem = chatHistory[chatHistory.length - 1];

    const systemTokens = estimateTokens(systemItem);
    let lastItemTokens = chatHistory.length > 1 ? estimateTokens(lastItem) : 0;
    let effectiveLastItem = lastItem;

    // If system + lastItem exceeds budget, try progressively:
    // 1. Truncate lastItem (current behavior)
    // 2. Replace system prompt with minimal version
    // 3. Truncate both to absolute minimum
    // Only fail if even the absolute minimum doesn't fit.
    let effectiveSystemItem = systemItem;
    let systemTokensAdjusted = systemTokens;

    if (chatHistory.length > 1 && systemTokensAdjusted + lastItemTokens > budget) {
      const availableForLastItem = budget - systemTokensAdjusted - 20;
      if (availableForLastItem > 100) {
        const fullText = getItemText(lastItem);
        const isToolOrSystemInject = RE_TOOL_OR_SYSTEM_INJECT.test(fullText);
        let keepChars = Math.floor(availableForLastItem * 3);
        // Tool/system inject messages must keep the START (JSON + snippets), not the tail.
        let truncatedText = isToolOrSystemInject ? fullText.slice(0, keepChars) : fullText.slice(-keepChars);
        let truncTokens = tokenize(truncatedText);

        let iterations = 0;
        while (truncTokens > availableForLastItem && keepChars > 200 && iterations < 5) {
          keepChars = Math.floor(keepChars * 0.75);
          truncatedText = isToolOrSystemInject ? fullText.slice(0, keepChars) : fullText.slice(-keepChars);
          truncTokens = tokenize(truncatedText);
          iterations++;
        }

        if (lastItem.response) {
          effectiveLastItem = { ...lastItem, response: [truncatedText] };
        } else {
          effectiveLastItem = { ...lastItem, text: truncatedText };
        }
        lastItemTokens = truncTokens + 10;
        console.log(`[ChatEngine] Context shift: truncated lastItem from ${fullText.length} to ${truncatedText.length} chars (${isToolOrSystemInject ? 'head' : 'tail'})`);
      }

      // If still doesn't fit after truncation, fall back to minimal system prompt
      if (systemTokensAdjusted + lastItemTokens > budget) {
        const MINIMAL_SYSTEM = 'You are a helpful AI assistant. Respond concisely.';
        const minimalSystemItem = systemItem.response
          ? { ...systemItem, response: [MINIMAL_SYSTEM] }
          : { ...systemItem, text: MINIMAL_SYSTEM };
        const minimalSystemTokens = tokenize(MINIMAL_SYSTEM) + 10;
        const availableWithMinimal = budget - minimalSystemTokens - 20;

        if (availableWithMinimal > 100) {
          effectiveSystemItem = minimalSystemItem;
          systemTokensAdjusted = minimalSystemTokens;
          console.log(`[ChatEngine] Context shift: replaced system prompt with minimal version (${systemTokens} → ${minimalSystemTokens} tokens)`);

          // Re-truncate lastItem with the freed-up space
          const fullText = getItemText(lastItem);
          if (minimalSystemTokens + lastItemTokens > budget) {
            const isToolOrSystemInject = RE_TOOL_OR_SYSTEM_INJECT.test(fullText);
            let keepChars = Math.floor(availableWithMinimal * 3);
            let truncatedText = isToolOrSystemInject ? fullText.slice(0, keepChars) : fullText.slice(-keepChars);
            let truncTokens = tokenize(truncatedText);
            let iterations = 0;
            while (truncTokens > availableWithMinimal && keepChars > 100 && iterations < 5) {
              keepChars = Math.floor(keepChars * 0.75);
              truncatedText = isToolOrSystemInject ? fullText.slice(0, keepChars) : fullText.slice(-keepChars);
              truncTokens = tokenize(truncatedText);
              iterations++;
            }
            if (lastItem.response) {
              effectiveLastItem = { ...lastItem, response: [truncatedText] };
            } else {
              effectiveLastItem = { ...lastItem, text: truncatedText };
            }
            lastItemTokens = truncTokens + 10;
          }
        } else {
          // Absolute minimum: minimal system + heavily truncated last item
          effectiveSystemItem = minimalSystemItem;
          systemTokensAdjusted = minimalSystemTokens;
          const fullText = getItemText(lastItem);
          const floorChars = Math.min(200, fullText.length);
          const truncatedText = fullText.slice(-floorChars);
          if (lastItem.response) {
            effectiveLastItem = { ...lastItem, response: [truncatedText] };
          } else {
            effectiveLastItem = { ...lastItem, text: truncatedText };
          }
          lastItemTokens = tokenize(truncatedText) + 10;
          console.log(`[ChatEngine] Context shift: extreme compression — minimal system + ${floorChars} char lastItem floor`);
        }
      }
    }

    // Fix A: Pin most recent actual user instruction (non-tool/system-inject) so it
    // survives context shifts. The model must always know what the user asked it to do.
    let pinnedUserIdx = -1;
    let pinnedUserText = '';
    for (let i = chatHistory.length - 2; i >= 1; i--) {
      const it = chatHistory[i];
      if (it.type === 'user' && !RE_TOOL_OR_SYSTEM_INJECT.test(String(it.text || ''))) {
        pinnedUserIdx = i;
        pinnedUserText = getItemText(it);
        break;
      }
    }

    // Sliding window with pinned user message reservation
    let used = systemTokensAdjusted + lastItemTokens;
    const keptIndices = new Set();

    // Reserve budget for pinned user message before greedy fill
    if (pinnedUserIdx >= 1) {
      const pinnedCost = estimateTokens(chatHistory[pinnedUserIdx]);
      if (used + pinnedCost + 20 <= budget) {
        used += pinnedCost;
        keptIndices.add(pinnedUserIdx);
      }
      // If pinned message is too large to fit, it will be picked up by the greedy
      // fill loop naturally (or dropped if truly no space — graceful degradation).
    }

    for (let i = chatHistory.length - 2; i >= 1; i--) {
      if (keptIndices.has(i)) continue; // Skip already-pinned index
      const cost = estimateTokens(chatHistory[i]);
      if (used + cost > budget) break;
      used += cost;
      keptIndices.add(i);
    }

    const droppedCount = (chatHistory.length - 2) - keptIndices.size;

    // Build droppedItems for summarizer consumption
    const droppedItems = [];
    for (let i = 1; i <= chatHistory.length - 2; i++) {
      if (!keptIndices.has(i)) droppedItems.push(chatHistory[i]);
    }

    const newHistory = [effectiveSystemItem];
    for (let i = 1; i <= chatHistory.length - 2; i++) {
      if (keptIndices.has(i)) newHistory.push(chatHistory[i]);
    }
    if (chatHistory.length > 1) newHistory.push(effectiveLastItem);

    if (droppedCount > 0) {
      this._writeContextStateFile({ chatHistory, keptIndices, getItemText, used, budget });
    }

    let finalHistory = newHistory;
    if (droppedCount > 0) {
      const syncSummary = this._extractDeterministicSummary(droppedItems, pinnedUserText);
      finalHistory = this._insertContextRotationNotice(finalHistory, droppedCount, pinnedUserText, syncSummary);
    }

    const measureOpts = {
      chatHistory: finalHistory,
      tokenizer,
      chatWrapper,
      functions: functions ?? this._shiftMeasureFunctions,
      documentFunctionParams: documentFunctionParams ?? this._shiftMeasureDocumentFunctionParams,
    };
    let renderedTokens = this._measureRenderedTokens(measureOpts);
    let verifyDrops = 0;
    const verifyDroppedItems = [];
    while (renderedTokens > budget && finalHistory.length > 2) {
      const [removed] = finalHistory.splice(1, 1);
      verifyDroppedItems.push(removed);
      verifyDrops++;
      renderedTokens = this._measureRenderedTokens({ ...measureOpts, chatHistory: finalHistory });
    }

    if (renderedTokens > budget && finalHistory.length > 1) {
      const MINIMAL_SYSTEM = 'You are a helpful AI assistant. Respond concisely.';
      const sys = finalHistory[0];
      finalHistory[0] = sys.response
        ? { ...sys, response: [MINIMAL_SYSTEM] }
        : { ...sys, text: MINIMAL_SYSTEM };
      renderedTokens = this._measureRenderedTokens({ ...measureOpts, chatHistory: finalHistory });
      console.log(`[ChatEngine] Context shift verify: minimal system, renderedTokens=${renderedTokens}`);
    }

    const totalDropped = droppedCount + verifyDrops;
    if (verifyDrops > 0) {
      const syncSummary = this._extractDeterministicSummary([...droppedItems, ...verifyDroppedItems], pinnedUserText);
      finalHistory = this._insertContextRotationNotice(finalHistory, totalDropped, pinnedUserText, syncSummary);
    }
    console.log(
      `[ChatEngine] Context shift: kept ${keptIndices.size} items, dropped ${droppedCount}, verifyDrops=${verifyDrops}, ` +
      `renderedTokens=${renderedTokens} budget=${budget}, estimateUsed=${used}`,
    );
    const allDroppedItems = [...droppedItems, ...verifyDroppedItems];
    return { chatHistory: finalHistory, metadata: { droppedCount: totalDropped, droppedItems: allDroppedItems, pinnedUserText } };
  }

  _buildToolPrompt(functions) {
    console.log(`[ChatEngine] _buildToolPrompt: ${Object.keys(functions || {}).length} functions`);
    const toolLines = Object.entries(functions).map(([name, def]) => {
      return `- ${name}: ${def.description || 'No description'}`;
    });
    const prompt = `\n\nYou have access to the following tools:\n${toolLines.join('\n')}\n\nTOOL USAGE RULES:\n- When the user asks you to create, write, edit, read, or delete files in their project, you MUST use the appropriate file tool (write_file, read_file, edit_file, append_to_file, delete_file). Do NOT output file contents inline.\n- When the user asks to change, update, fix, or tweak an existing file (already created or read this session), use edit_file or replace_in_file on that path — not write_file to a new path unless they asked for a new file or full rewrite.\n- When the user asks you to find, search, or look for something in their code, use grep_search or find_files.\n- When the user asks to list or explore project structure, use list_directory.\n- When the user asks to run a command, script, or install something, use run_command.\n- When the user asks to search the web or look something up online, use web_search then immediately fetch_webpage on the first and second ranked result URLs in the same continuation before answering (if only one hit, fetch that URL). Do not ask the user whether to fetch. Do not list the project directory in the same tool round as web_search/fetch_webpage unless the user asked about the project.\n- For large project rules (>~2KB), use write_file to .guide/rules/<name>.md instead of embedding the full document in save_rule JSON.\n- NEVER write_file or edit_file application source under .guide/ (e.g. not .guide/plans/index.html). Use project-root paths like index.html, src/..., or public/... — .guide/plans is for *.plan.md plan files only.\n- When the user asks a general question, wants an explanation, or asks you to review code you already have, respond with text directly.\n- You can chain tools: use read_file to see existing code, then edit_file to modify it, then run_command to test it.\n- Always prefer tools over inline code when the user wants changes to their actual project files.`;
    console.log(`[ChatEngine] _buildToolPrompt: built ${prompt.length} chars`);
    return prompt;
  }

  _compiledLlamaBuildPath() {
    return path.join(__dirname, 'node_modules', 'node-llama-cpp', 'llama', 'lastBuild.json');
  }

  /** Legacy installers ship source-built llama only (no @node-llama-cpp prebuilts). */
  _usesSourceBuiltLlama() {
    if (!fs.existsSync(this._compiledLlamaBuildPath())) return false;
    const prebuiltRoot = path.join(__dirname, 'node_modules', '@node-llama-cpp');
    if (!fs.existsSync(prebuiltRoot)) return true;
    try {
      return fs.readdirSync(prebuiltRoot).filter((n) => !n.startsWith('.')).length === 0;
    } catch {
      return true;
    }
  }

  async _createLlamaRuntime(getLlama, gpuOpt) {
    if (fs.existsSync(this._compiledLlamaBuildPath())) {
      console.log('[ChatEngine] getLlama(lastBuild) — compiled llama.cpp (b9253+ pipeline)');
      return getLlama('lastBuild', { gpu: gpuOpt });
    }
    if (this._usesSourceBuiltLlama()) {
      console.log('[ChatEngine] getLlama(lastBuild) — legacy/source-built binary');
      return getLlama('lastBuild', { gpu: gpuOpt });
    }
    return getLlama({ gpu: gpuOpt });
  }

  _getNodeLlamaCppPath() {
    console.log('[ChatEngine] _getNodeLlamaCppPath START');
    try {
      const resolved = require.resolve('node-llama-cpp');
      console.log(`[ChatEngine] _getNodeLlamaCppPath resolved: ${resolved}`);
      return resolved;
    } catch (e) {
      const fallback = path.join(__dirname, '..', 'node_modules', 'node-llama-cpp', 'dist', 'index.js');
      console.warn(`[ChatEngine] _getNodeLlamaCppPath fallback: ${fallback} (error: ${e.message})`);
      return fallback;
    }
  }

  /**
   * Convert mcpToolServer tool definitions to node-llama-cpp ChatModelFunctions format.
   * mcpToolServer format: [{ name, description, parameters: { paramName: { type, description, required } } }]
   * ChatModelFunctions format: { name: { description, params: GbnfJsonSchema } }
   *
   * Note: In GBNF JSON Schema, ALL properties in an object schema are required.
   * We only include required params to avoid forcing the model to output optional values.
   */
  static convertToolDefs(toolDefs) {
    console.log(`[ChatEngine] convertToolDefs: ${toolDefs?.length || 0} tool definitions`);
    const functions = {};
    for (const tool of (toolDefs || [])) {
      const properties = {};
      if (tool.parameters) {
        for (const [paramName, paramDef] of Object.entries(tool.parameters)) {
          // Only include required parameters (GBNF makes all properties required)
          if (paramDef.required === false) continue;

          const prop = { type: paramDef.type || 'string' };
          if (paramDef.description) prop.description = paramDef.description;
          properties[paramName] = prop;
        }
      }

      // Strip the format hint from descriptions (e.g. 'Format: {"tool":"name",...}')
      let desc = tool.description || '';
      const formatIdx = desc.indexOf('Format:');
      if (formatIdx > 0) desc = desc.substring(0, formatIdx).trim();

      functions[tool.name] = {
        description: desc,
        params: Object.keys(properties).length > 0
          ? { type: 'object', properties }
          : undefined,
      };
    }
    console.log(`[ChatEngine] convertToolDefs: converted ${Object.keys(functions).length} functions`);
    return functions;
  }
}

// Default set of tools enabled out of the box
ChatEngine.DEFAULT_ENABLED_TOOLS = new Set([
  // Files
  'read_file', 'write_file', 'edit_file', 'append_to_file',
  'delete_file', 'rename_file', 'copy_file',
  'list_directory', 'create_directory', 'find_files', 'grep_search',
  'search_codebase', 'search_in_file', 'replace_in_files',
  'get_project_structure', 'get_file_info', 'diff_files',
  // Terminal
  'run_command',
  // Web
  'web_search', 'fetch_webpage',
  // Browser
  'browser_navigate', 'browser_snapshot', 'browser_click',
  'browser_type', 'browser_get_content', 'browser_screenshot',
  'browser_evaluate', 'browser_fill_form', 'browser_select_option',
  'browser_scroll', 'browser_wait', 'browser_wait_for',
  'browser_back', 'browser_press_key', 'browser_hover',
  'browser_drag', 'browser_tabs', 'browser_handle_dialog',
  'browser_console_messages', 'browser_file_upload',
  'browser_resize', 'browser_get_url', 'browser_get_links',
  'browser_close',
  // Memory
  'save_memory', 'get_memory', 'list_memories',
  // Planning
  'write_todos', 'update_todo',
  // Interaction
  'ask_question',
]);

/** Same identity + tools as local; cloud path appends CLOUD_STYLE only when tools are enabled. */
function buildCloudSystemPrompt({ userSystemPrompt, baseSystemPrompt, customInstructions, toolPrompt }) {
  let text = (userSystemPrompt && String(userSystemPrompt).trim()) || baseSystemPrompt || SYSTEM_PROMPT;
  if (customInstructions && String(customInstructions).trim()) {
    text += `\n\n${String(customInstructions).trim()}`;
  }
  if (toolPrompt && String(toolPrompt).trim()) {
    text += `\n\n${String(toolPrompt).trim()}`;
  }
  text +=
    '\n\n## Cloud output channels\n' +
    'Put reasoning in your reasoning stream only (plain language). ' +
    'Emit executable tool calls as JSON in the assistant message body, not inside reasoning. ' +
    'Never paste full file contents or raw tool JSON in reasoning; use write_file/edit_file tools instead.';
  return text;
}

/**
 * Shared non-model context layers (date/OS/project/guide instructions/editor) for local + cloud.
 */
function buildAgentSystemPromptLayers({
  projectPath,
  guideInstructionsPath,
  editorContext,
  editorDiagnostics,
} = {}) {
  let layers = '';
  const now = new Date();
  const dateStr = now.toISOString().split('T')[0];
  const timeStr = now.toTimeString().split(' ')[0];
  const platform = `${os.type()} ${os.release()} (${os.platform()})`;
  layers += `\n\nCurrent date: ${dateStr}\nCurrent time: ${timeStr}\nOperating system: ${platform}`;
  if (projectPath) {
    layers += `\nProject directory: ${projectPath}\nAll file tools operate relative to this directory.`;
  }
  if (guideInstructionsPath) {
    try {
      const fs = require('fs');
      const instrPath = path.isAbsolute(guideInstructionsPath)
        ? guideInstructionsPath
        : path.join(projectPath || process.cwd(), guideInstructionsPath);
      if (fs.existsSync(instrPath)) {
        const guideContent = fs.readFileSync(instrPath, 'utf-8').trim();
        if (guideContent) {
          layers += `\n\n## Project Instructions (from ${guideInstructionsPath})\n${guideContent}`;
        }
      }
    } catch (e) {
      console.warn('[ChatEngine] Guide instructions load failed:', e.message);
    }
  }
  if (editorContext) {
    const ec = editorContext;
    const parts = [];
    if (ec.activeFilePath) {
      const rel = projectPath
        ? ec.activeFilePath.replace(projectPath.replace(/\\/g, '/'), '').replace(/^\//, '')
        : ec.activeFilePath;
      let ctxLine = `Active file: ${rel}`;
      if (ec.cursorLine) ctxLine += ` (cursor at line ${ec.cursorLine})`;
      parts.push(ctxLine);
    }
    if (ec.recentSaves?.length > 0) {
      const saveNames = ec.recentSaves
        .map((s) => (projectPath
          ? s.filePath.replace(projectPath.replace(/\\/g, '/'), '').replace(/^\//, '')
          : s.filePath))
        .filter(Boolean);
      if (saveNames.length > 0) parts.push(`Recently saved: ${saveNames.join(', ')}`);
    }
    const diagStore = editorDiagnostics;
    if (diagStore) {
      let totalErrors = 0;
      const errorFiles = [];
      for (const [fp, d] of Object.entries(diagStore)) {
        if (d.errors > 0) {
          totalErrors += d.errors;
          const rel = projectPath
            ? fp.replace(projectPath.replace(/\\/g, '/').toLowerCase(), '').replace(/^\//, '')
            : fp;
          errorFiles.push(`${rel} (${d.errors} errors)`);
        }
      }
      if (totalErrors > 0) {
        parts.push(`Diagnostics: ${totalErrors} errors in ${errorFiles.slice(0, 5).join(', ')}`);
      }
    }
    if (parts.length > 0) {
      layers += `\n\n## Editor Context\n${parts.join('\n')}`;
    }
  }
  return layers;
}

module.exports = {
  ChatEngine,
  buildEngineLoadSettings,
  buildTodoProgressHint,
  buildBudgetProportionalToolPrompt,
  resolveAgentMinToolPromptChars,
  preferCompactToolCatalogForTier,
  shouldPreferCompactToolCatalog,
  computeUnifiedVramBudget,
  SYSTEM_PROMPT,
  buildCloudSystemPrompt,
  buildAgentSystemPromptLayers,
  _sanitizeFileSnippetText,
  _sfPreparePlainFenceFlushPayload,
  _sfIsPlainMarkdownFence,
  _sfFenceHeaderShouldStreamPlain,
  _sfFenceBufferLooksLikeToolJson,
  _sfShouldRouteAgentCodeFence,
  _sfInferAgentFenceFilePath,
  _sfIsAgentFileFenceMode,
  _sfRerouteThinkContentToFile,
  _sfExtractAgentFenceBody,
  _sfStripPlainCodeFencesFromProse,
};