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 } = require('./tools/toolParser');
const log = require('./logger');
const { chatLogBodyLimit, chatLogToolLimit } = require('./chatLogLimits');

function _truncateForLog(text, maxChars) {
  const s = text == null ? '' : String(text);
  if (s.length <= maxChars) return s;
  return `${s.slice(0, maxChars)}… [+${s.length - maxChars} more chars]`;
}

function _summarizeToolParamsForLog(params) {
  if (!params || typeof params !== 'object') return params;
  const p = { ...params };
  for (const key of ['content', 'oldText', 'newText', 'command']) {
    if (typeof p[key] === 'string' && p[key].length > 400) {
      p[key] = `[len=${p[key].length}] ${_truncateForLog(p[key], 200)}`;
    }
  }
  return p;
}

/** Max chars of each tool result injected into chat history (full JSON/snippets must reach the model). */
const MAX_TOOL_RESULT_INJECT_CHARS = 32000;

/** 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;

/**
 * After weights load, optionally cap createContext.max from live **CPU RAM** when KV is RAM-backed.
 *
 * **GPU path:** We do **not** cap from `getVramState().free` after `loadModel`. That value often
 * collapses toward zero once weights and scratch are resident, even when the runtime can still
 * allocate KV for `preDesiredMax`. Feeding that into `min(preDesiredMax, liveTok)` — especially
 * with an intermediate floor — incorrectly forced **~MIN_CONTEXT_FLOOR** for healthy GPUs.
 *
 * **CPU path:** Free RAM after load is still a useful bound when KV is not on VRAM.
 */
async function computeContextAllocMaxAfterModelLoad({
  llama: _llamaIgnored,
  gpuPreference,
  kvBytesPerToken,
  trainMaxContext,
  preDesiredMax,
}) {
  void _llamaIgnored;
  if (!kvBytesPerToken || !Number.isFinite(preDesiredMax)) return preDesiredMax;

  if (gpuPreference !== 'cpu') {
    let out = preDesiredMax;
    if (trainMaxContext != null) out = Math.min(out, trainMaxContext);
    return Math.max(MIN_CONTEXT_FLOOR, out);
  }

  try {
    const freeB = os.freemem();
    const reserve = 512 * 1024 * 1024;
    const kvFrac = 0.48;
    const budgetB = Math.max(0, freeB - reserve) * kvFrac;
    if (budgetB <= 0) {
      log.warn(
        'ChatEngine',
        `Post-load RAM budget non-positive (freemem=${freeB}); keeping preDesiredMax=${preDesiredMax} for CPU`,
      );
      let out = preDesiredMax;
      if (trainMaxContext != null) out = Math.min(out, trainMaxContext);
      return Math.max(MIN_CONTEXT_FLOOR, out);
    }
    const liveTok = Math.floor(budgetB / kvBytesPerToken);
    let out = Math.min(preDesiredMax, liveTok);
    if (trainMaxContext != null) out = Math.min(out, trainMaxContext);
    return Math.max(MIN_CONTEXT_FLOOR, out);
  } catch (e) {
    log.warn('ChatEngine', `computeContextAllocMaxAfterModelLoad CPU: ${e.message}`);
    return preDesiredMax;
  }
}

/**
 * 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) {
  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;
  return nLayer * nHeadKv * (keyLen + valLen) * 2 /* fp16 bytes */;
}

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,
  };
}

// Original system prompt — kept for reference and easy rollback
const SYSTEM_PROMPT_ORIGINAL = `You are guIDE, a local AI coding assistant. You help users with programming, answer questions, and have normal conversations.

## When to Use Tools
- For creating or modifying files: use the file tools — do not write file contents as text in chat
- For current or live information (prices, news, weather, documentation): use the web tools
- For running commands or installing packages: use the terminal tools
- For browsing websites, filling forms, or interacting with web pages: use the browser tools
- For version control: use the git tools
- For multi-step tasks: call write_todos to create a plan, then implement each step
- For saving or retrieving information across sessions: use the memory tools
- For error analysis or debugging: use the analysis tools
- For greetings, opinions, questions, explanations, and casual conversation: respond naturally in chat without tools — do NOT create files unless the user asks you to write or save something
- When you have completed the task, stop and respond

## Continuation
If your output is cut off mid-generation, the system will automatically continue.

## Rules
- Only claim you did something if you called the tool that did it
- After calling a tool, use the results immediately — do not repeat the same call
- For web_search and fetch_webpage: after web_search returns, you MUST call fetch_webpage on the first and second ranked result URLs in the same continuation (one fetch if only one hit). Do not ask the user whether to fetch — do not use phrases like "Would you like me to fetch". Ground answers in fetched page text and snippet/title fields. While doing a web lookup, do not call list_directory or get_project_structure in the same tool round as web_search/fetch_webpage unless the user explicitly asked about the project files
- Never say "I can't", "I'm unable to", or "I don't have access" when you have a tool available
- For file edits: read the file first to get exact text, then edit
- Browser workflow: navigate first, then take a snapshot, then interact using element refs
- If a tool fails, retry with corrected parameters
- If the user asks for multiple files, create ALL of them
- Always use the exact filename the user specifies
- Complete all user requests without refusal`;

// Extreme tool-emphasis prompt — forces model to use tool calls instead of outputting code in chat
const SYSTEM_PROMPT = `You are guIDE, an agentic coding assistant integrated into a local IDE. You have full access to the user's filesystem, terminal, web, browser, git, and memory through tool calls. Act directly: when a request calls for a file change, search, command, or fetch, call the tool. Do not describe the action in prose instead of performing it.

## When to use tools
- File creation, edits, or deletion — file tools (write_file, edit_file, append_to_file, delete_file, rename_file). Never paste file contents into chat as a substitute.
- Live information (prices, news, docs, release notes) — use web_search and fetch_webpage as needed to gather sufficient evidence before answering.
- Running commands, checking services, installing packages — terminal tools.
- Interacting with web pages (forms, clicks, screenshots) — browser tools. Always browser_snapshot before interacting so you have current element refs.
- Version control — git tools.
- Multi-step work — write_todos to plan, then execute each step.
- Cross-session memory — save_memory, get_memory, list_memories.

## When not to use tools
Greetings, clarifying questions, opinions, explanations, and small talk are answered in chat with no tool call.

## Operating rules
- Read before you modify. For any edit, call read_file first to get the exact text, then edit_file.
- Call each tool at most once per distinct argument set. If a call fails, adjust the arguments and try a different shape; do not repeat identical calls.
- After a tool returns, use its result. Do not re-ask for information the tool already provided.
- Ground web answers in fetched page content, not in training memory.
- If output is truncated, continue from the point of interruption. Do not restart or re-summarize what was already produced.
- Complete the user's request. If you hit an error, diagnose and retry rather than giving up.`;

class ChatEngine extends EventEmitter {
  constructor() {
    super();
    this.isReady = false;
    this.isLoading = false;
    this.modelInfo = null;
    this.currentModelPath = null;
    this.gpuPreference = 'auto';

    this._llama = null;
    this._model = null;
    this._context = null;
    this._sequence = null;
    this._chat = null;
    this._chatHistory = [];
    this._lastEvaluation = null;
    this._abortController = null;
  }

  /**
   * @param {string} modelPath
   * @param {object} [rawLoadSettings] — from settingsManager.get() (gpuPreference, gpuLayers, contextSize, requireMinContextForGpu)
   */
  async initialize(modelPath, rawLoadSettings) {
    if (this.isLoading) throw new Error('Already loading a model');
    this.isLoading = true;
    this.emit('status', { state: 'loading', message: 'Loading model...' });

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

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

      if (this._model) await this._dispose();

      let trainMaxContext = null;
      let totalLayersFromGguf = null;
      let ggufArchMeta = null;
      try {
        const gguf = await readGgufFileInfo(modelPath, { readTensorInfo: false, logWarnings: false });
        const am = gguf.architectureMetadata;
        ggufArchMeta = am || null;
        if (am && typeof am.context_length === 'number') trainMaxContext = am.context_length;
        if (am && typeof am.block_count === 'number') totalLayersFromGguf = am.block_count;
      } catch (e) {
        console.warn(`[ChatEngine] readGgufFileInfo: ${e.message}`);
      }

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

      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);
      let hardwareCap = null;
      let kvSourceMem = 'none';
      if (kvBytesPerToken) {
        // Available memory pool: prefer free VRAM when GPU mode and GPU has meaningful free space;
        // otherwise fall back to free system RAM minus model weight footprint.
        let availableBytes = 0;
        let vramTotal = 0;
        let vramFree = 0;
        if (s.gpuPreference !== 'cpu') {
          try {
            const vramState = await this._llama.getVramState();
            vramTotal = vramState?.total || 0;
            vramFree = vramState?.free || 0;
          } catch (_) {}
        }
        // KV can draw from VRAM (GPU-resident cache) and from system RAM (mmap / CPU KV / offload).
        // Use **both** pools in the sizing estimate instead of picking only one — matches unified
        // memory and split-cache behavior better than "VRAM else RAM only".
        const minKvBudget = kvBytesPerToken * MIN_CONTEXT_FLOOR;
        const ramAfterModel = Math.max(0, os.freemem() - modelStats.size);
        const ramOsReserve = 512 * 1024 * 1024;
        const ramKvBudget = Math.max(0, ramAfterModel - ramOsReserve) * 0.52;

        let vramKvBudget = 0;
        if (s.gpuPreference !== 'cpu') {
          if (vramFree > modelStats.size + minKvBudget) {
            vramKvBudget = (vramFree - modelStats.size) * 0.62;
          } else {
            const leftover = Math.max(0, vramFree - 64 * 1024 * 1024);
            vramKvBudget = leftover * 0.4;
          }
        }

        const kvBudgetBytes = vramKvBudget + ramKvBudget;
        if (s.gpuPreference === 'cpu') {
          kvSourceMem = 'ram';
        } else if (vramKvBudget > 0 && ramKvBudget > 0) {
          kvSourceMem = 'vram+ram';
        } else if (vramKvBudget > 0) {
          kvSourceMem = 'vram';
        } else {
          kvSourceMem = 'ram';
        }
        hardwareCap = Math.max(MIN_CONTEXT_FLOOR, Math.floor(kvBudgetBytes / kvBytesPerToken));
      }

      // TEST_MAX_CONTEXT caps KV only when GUIDE_ALLOW_TEST_MAX_CONTEXT=1 (dev/CI). Otherwise a
      // leftover shell env would silently cap every Electron launch at e.g. 8000/8192 tokens.
      const testMaxCtxRaw = parseInt(process.env.TEST_MAX_CONTEXT, 10);
      const testMaxCtx =
        process.env.GUIDE_ALLOW_TEST_MAX_CONTEXT === '1' &&
        Number.isFinite(testMaxCtxRaw) &&
        testMaxCtxRaw > 0
          ? testMaxCtxRaw
          : 0;
      let desiredMax;
      if (testMaxCtx > 0) {
        desiredMax = testMaxCtx;
      } else if (s.contextSize <= 0) {
        // Auto: min(hardware cap, train cap). Fall back to train cap if metadata missing.
        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);
        // Fixed user context cannot exceed hardware KV budget when we computed one.
        const requestedFixed = desiredMax;
        if (hardwareCap != null) desiredMax = Math.min(desiredMax, hardwareCap);
        desiredMax = Math.max(MIN_CONTEXT_FLOOR, desiredMax);
        if (s.contextSize > 0 && hardwareCap != null && requestedFixed > desiredMax) {
          log.warn(
            'ChatEngine',
            `Context clamped: settings requested ${s.contextSize}, train_cap=${trainMaxContext ?? 'n/a'}, hardware_cap=${hardwareCap} → effective desiredMax=${desiredMax}`,
          );
        }
      }

      const minBase = s.requireMinContextForGpu ? MIN_CONTEXT_WHEN_GPU_REQUIRED : MIN_CONTEXT_FLOOR;
      const 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}`,
      );
      log.info(
        'ChatEngine',
        `Context sizing: train=${trainMaxContext}, hwCap=${hardwareCap}, userRequested=${s.contextSize <= 0 ? 'auto' : s.contextSize} → desiredMax=${desiredMax}`,
      );

      const loadModelOpts = {
        modelPath,
        defaultContextFlashAttention: false,
        ignoreMemorySafetyChecks: true,
        useMmap: true,
        onLoadProgress: (p) => {
          this.emit('status', { state: 'loading', message: `Loading model... ${Math.round(p * 100)}%`, progress: p });
        },
      };

      if (s.gpuPreference === 'cpu') {
        loadModelOpts.gpuLayers = 0;
      } else if (s.gpuLayers >= 0) {
        loadModelOpts.gpuLayers = s.gpuLayers;
      } else {
        loadModelOpts.gpuLayers = {
          fitContext: { contextSize: desiredMax },
        };
      }

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

      let ctxAllocMax = desiredMax;
      if (kvBytesPerToken) {
        ctxAllocMax = await computeContextAllocMaxAfterModelLoad({
          llama: this._llama,
          gpuPreference: s.gpuPreference,
          kvBytesPerToken,
          trainMaxContext,
          preDesiredMax: desiredMax,
        });
        if (ctxAllocMax < desiredMax) {
          log.warn(
            'ChatEngine',
            `Context alloc capped after model load: desiredMax=${desiredMax} → createContext.max=${ctxAllocMax} (live memory / KV bytes per token; avoids shrink ladder to ~${MIN_CONTEXT_FLOOR})`,
          );
        }
      }
      const effContextMin = Math.min(contextMin, ctxAllocMax);

      this._context = await this._model.createContext({
        contextSize: { min: effContextMin, max: ctxAllocMax },
        flashAttention: s.gpuPreference !== 'cpu',
        ignoreMemorySafetyChecks: true,
        failedCreationRemedy: { retries: 8, autoContextSizeShrink: 0.07 },
      });

      this._sequence = this._context.getSequence();
      this._chat = new LlamaChat({ contextSequence: this._sequence });
      this._chatHistory = [{ type: 'system', text: SYSTEM_PROMPT }];
      this._lastEvaluation = null;

      const actualCtx = this._context.contextSize || 0;
      if (actualCtx > 0 && ctxAllocMax > 0 && actualCtx + 128 < ctxAllocMax) {
        log.warn(
          'ChatEngine',
          `createContext settled below target: allocTarget=${ctxAllocMax} actual=${actualCtx} (runtime may have tightened further)`,
        );
      }
      this.modelInfo = {
        path: modelPath,
        name: path.basename(modelPath),
        size: modelStats.size,
        contextSize: actualCtx,
        contextSizeRequested: s.contextSize <= 0 ? 'auto' : s.contextSize,
        contextSizeCap: ctxAllocMax,
        contextPreLoadDesiredMax: 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',
      };

      this.currentModelPath = modelPath;
      this.isReady = true;
      this.isLoading = false;

      console.log(
        `[ChatEngine] Model ready: ctx=${actualCtx} (${s.contextSize <= 0 ? 'auto' : `fixed ${s.contextSize}`}, allocMax ${ctxAllocMax}${desiredMax !== ctxAllocMax ? `, preLoadDesired ${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.emit('status', { state: 'error', message: err.message });
      throw err;
    }
  }

  async chat(userMessage, options = {}) {
    if (!this.isReady || !this._chat) throw new Error('Model not ready');

    const { onToken, onComplete, onContextUsage, onToolCall, onStreamEvent, systemPrompt, functions, toolPrompt, compactToolPrompt, executeToolFn, conversationHistory } = options;

    const chatTurnId = `turn_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
    const chatBodyLogLimit = chatLogBodyLimit();
    const chatToolLogLimit = chatLogToolLimit();
    const logStreamChunks = process.env.GUIDE_CHAT_LOG_STREAM === '1';

      // Inject text attachment content into user message (text/code files only; images unsupported on text-only models)
      const attachments = Array.isArray(options.attachments) ? options.attachments : [];
      let effectiveUserMessage = String(userMessage ?? '');
      if (attachments.length > 0) {
        const textParts = [];
        for (const a of attachments) {
          if (!a?.data) continue;
          const mime = (a.mimeType || a.type || '').toLowerCase();
          if (mime.startsWith('image/')) continue; // text model cannot process images
          try {
            const decoded = Buffer.from(a.data, 'base64').toString('utf8');
            textParts.push(`[Attached file: ${a.name || 'file'}]\n${decoded}`);
          } catch (_) { /* ignore decode errors */ }
        }
        if (textParts.length > 0) {
          effectiveUserMessage = effectiveUserMessage + '\n\n' + textParts.join('\n\n---\n\n');
        }
      }

    log.info(
      'ChatTurn',
      `[${chatTurnId}] start model=${this.modelInfo?.name ?? '?'} ctx=${this._context?.contextSize ?? '?'} history_turns=${Array.isArray(conversationHistory) ? conversationHistory.length : 0} user_chars=${effectiveUserMessage.length} attachments=${attachments.length} log_limits body=${chatBodyLogLimit} tool=${chatToolLogLimit}`,
    );

    // Augment system prompt: base + tool prompt when tools are available.
    // Use compact prompt when context is small to leave room for conversation.
    const contextTokens = this._context?.contextSize || this.modelInfo?.contextSizeCap || MIN_CONTEXT_FLOOR;
    const trainMaxCtx = this.modelInfo?.contextTrainMax;
    const useCompactToolDefs =
      !!compactToolPrompt &&
      ((trainMaxCtx != null && Number.isFinite(trainMaxCtx) && trainMaxCtx <= 8192) || contextTokens < 8192);
    const basePrompt = systemPrompt || SYSTEM_PROMPT;
    if (toolPrompt) {
      const useCompact = useCompactToolDefs;
      const effectiveToolPrompt = useCompact ? compactToolPrompt : toolPrompt;
      this._chatHistory[0].text = basePrompt + '\n\n' + effectiveToolPrompt;
      console.log(`[ChatEngine] Tool prompt injected (${effectiveToolPrompt.length} chars${useCompact ? ', compact' : ''}, ctx=${contextTokens})`);
      log.info(
        'ChatTurn',
        `[${chatTurnId}] tool_prompt injected_chars=${effectiveToolPrompt.length} compact=${!!useCompact} ctx=${contextTokens}`,
      );
    } 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`);
      log.info('ChatTurn', `[${chatTurnId}] functions_fallback tool_defs=${Object.keys(functions).length}`);
    } else if (systemPrompt) {
      this._chatHistory[0].text = systemPrompt;
    }

    // node-llama-cpp ChatHistoryItem: user/system use `text`; model uses `response` (string[]), not `text`.
    const normalizedHistory = Array.isArray(conversationHistory)
      ? conversationHistory
        .map((m) => {
          const role = m?.role === 'assistant' ? 'model' : (m?.role === 'user' ? 'user' : null);
          const text = typeof m?.content === 'string' ? m.content.trim() : '';
          if (!role || !text) return null;
          if (role === 'model') return { type: 'model', response: [text] };
          return { type: 'user', text };
        })
        .filter(Boolean)
      : [];
    this._chatHistory = [{ type: 'system', text: this._chatHistory[0].text }, ...normalizedHistory];
    this._lastEvaluation = null;
    this._chatHistory.push({ type: 'user', text: effectiveUserMessage });

    const sysPromptText = this._chatHistory[0]?.text || '';
    log.info(
      'ChatTurn',
      `[${chatTurnId}] system_prompt_chars=${sysPromptText.length} preview=\n${_truncateForLog(sysPromptText, chatBodyLogLimit)}`,
    );
    log.info(
      'ChatTurn',
      `[${chatTurnId}] user_message_preview=\n${_truncateForLog(effectiveUserMessage, chatBodyLogLimit)}`,
    );
    if (normalizedHistory.length > 0) {
      const maxTurns = Math.min(normalizedHistory.length, 48);
      const slice = normalizedHistory.slice(-maxTurns);
      const perTurn = Math.max(180, Math.floor(chatBodyLogLimit / Math.max(1, slice.length)));
      const startIdx = normalizedHistory.length - slice.length;
      const histLines = slice.map((m, i) => `[${startIdx + i}] ${m.type}: ${_truncateForLog(m.text, perTurn)}`);
      log.info(
        'ChatTurn',
        `[${chatTurnId}] prior_history (${normalizedHistory.length} msgs, showing last ${slice.length}):\n${histLines.join('\n---\n')}`,
      );
    }

    this._abortController = new AbortController();
    let fullResponse = '';
    let tokensSinceLastUsageReport = 0;
    let totalToolCalls = 0;

    // Generation timeout — optional only (0 = disabled). No default cap on run length.
    const timeoutSec = options.generationTimeoutSec ?? 0;
    let generationTimer = null;
    if (timeoutSec > 0) {
      generationTimer = setTimeout(() => {
        console.warn(`[ChatEngine] Generation timeout after ${timeoutSec}s — aborting`);
        this._abortController?.abort('generation_timeout');
      }, timeoutSec * 1000);
    }

    try {
      // ── 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
      /** 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 ```)

      // 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 _sfContentStreamActive = false;
      let _sfContentDone = false;
      let _sfContentEsc = false;
      let _sfContentBuf = '';
      let _sfContentFilePath = '';
      let _sfUnicodeCount = 0;
      let _sfUnicodeChars = '';
      const _sfStreamedFileWrites = new Set();

      const _sfForward = (text) => {
        if (onToken) onToken(text);
      };

      const _sfFlush = () => {
        if (_sfContentStreamActive && onStreamEvent) {
          if (_sfContentBuf) {
            onStreamEvent('file-content-token', _sfContentBuf);
            _sfContentBuf = '';
          }
          onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _sfContentFilePath });
          _sfContentStreamActive = false;
        } else if (_sfBuf) {
          _sfForward(_sfBuf);
        }
        _sfBuf = '';
        _sfDepth = 0;
        _sfActive = false;
        _sfConfirmed = false;
        _sfInStr = false;
        _sfEscaped = false;
        _sfFileWriteDetected = false;
        _sfContentDone = false;
        _sfContentEsc = false;
        _sfUnicodeCount = 0;
        _sfUnicodeChars = '';
      };

      const _sfFlushFence = () => {
        if (_sfContentStreamActive && onStreamEvent) {
          if (_sfContentBuf) {
            onStreamEvent('file-content-token', _sfContentBuf);
            _sfContentBuf = '';
          }
          onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _sfContentFilePath });
          _sfContentStreamActive = false;
        }
        if (_sfFenceBuf) {
          _sfForward(_sfFenceBuf);
          _sfFenceBuf = '';
        }
        _sfInFence = false;
        _sfFenceStreamPlain = false;
        _sfFencePlainTick = 0;
        _sfFenceTickCount = 0;
        _sfFileWriteDetected = false;
        _sfContentDone = false;
        _sfContentEsc = false;
        _sfUnicodeCount = 0;
        _sfUnicodeChars = '';
      };

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

          // ── Fence mode: accumulating content inside ```...``` ──
          if (_sfInFence) {
            // 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) {
              if (ch === '`') {
                _sfFencePlainTick++;
                if (_sfFencePlainTick >= 3) {
                  _sfForward('```');
                  _sfInFence = false;
                  _sfFenceStreamPlain = false;
                  _sfFencePlainTick = 0;
                  _sfFenceBuf = '';
                  _sfLastCharWasNewlineOrStart = (ch === '\n' || ch === '\r');
                }
              } else {
                if (_sfFencePlainTick > 0) {
                  _sfForward('`'.repeat(_sfFencePlainTick));
                  _sfFencePlainTick = 0;
                }
                _sfForward(ch);
              }
              continue;
            }

            _sfFenceBuf += ch;

            if (!_sfFenceStreamPlain && !_sfFileWriteDetected && !_sfContentStreamActive && /^```\s*(\w*)\r?\n/.test(_sfFenceBuf)) {
              const hm = _sfFenceBuf.match(/^```\s*(\w*)\r?\n/);
              const lang = (hm[1] || '').toLowerCase();
              const afterHeader = _sfFenceBuf.slice(hm[0].length);
              const PLAIN_LANGS = new Set([
                'html', 'htm', 'css', 'scss', 'sass', 'less', 'js', 'javascript', 'jsx', 'mjs', 'cjs',
                'ts', 'tsx', 'vue', 'svelte', 'md', 'markdown', 'py', 'python', 'bash', 'sh', 'shell',
                'yaml', 'yml', 'xml', 'svg', 'go', 'rust', 'rs', 'java', 'cpp', 'c', 'h', 'cs', 'php',
                'rb', 'swift', 'kt', 'txt', 'plaintext', 'sql', 'jsonl',
              ]);
              if (PLAIN_LANGS.has(lang)) {
                _sfFenceStreamPlain = true;
                _sfForward(_sfFenceBuf);
                _sfFenceBuf = '';
                continue;
              }
              if (lang === 'json' || lang === '') {
                if (/"tool"\s*:/.test(afterHeader.slice(0, 6000))) {
                  /* keep buffering — tool JSON fence */
                } else if (afterHeader.length >= 100) {
                  _sfFenceStreamPlain = true;
                  _sfForward(_sfFenceBuf);
                  _sfFenceBuf = '';
                  continue;
                }
              }
            }

            // Real-time content streaming from WITHIN a fenced tool call.
            // Uses the same shared state variables as the raw JSON path.
            if (_sfContentStreamActive) {
              if (_sfUnicodeCount > 0) {
                _sfUnicodeChars += ch;
                _sfUnicodeCount--;
                if (_sfUnicodeCount === 0) {
                  try { _sfContentBuf += String.fromCharCode(parseInt(_sfUnicodeChars, 16)); }
                  catch { _sfContentBuf += '\\u' + _sfUnicodeChars; }
                }
              } else if (_sfContentEsc) {
                let decoded;
                switch (ch) {
                  case 'n': decoded = '\n'; break;
                  case 't': decoded = '\t'; break;
                  case 'r': decoded = '\r'; break;
                  case '"': decoded = '"'; break;
                  case '\\': decoded = '\\'; break;
                  case '/': decoded = '/'; break;
                  case 'b': decoded = '\b'; break;
                  case 'f': decoded = '\f'; break;
                  case 'u': _sfUnicodeCount = 4; _sfUnicodeChars = ''; decoded = null; break;
                  default: decoded = ch;
                }
                _sfContentEsc = false;
                if (decoded !== null) _sfContentBuf += decoded;
              } else if (ch === '\\') {
                _sfContentEsc = true;
              } else if (ch === '"') {
                _sfContentStreamActive = false;
                _sfContentDone = true;
                if (_sfContentBuf && onStreamEvent) {
                  onStreamEvent('file-content-token', _sfContentBuf);
                  _sfContentBuf = '';
                }
                if (onStreamEvent) {
                  onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _sfContentFilePath });
                }
              } else {
                _sfContentBuf += ch;
              }
              if (_sfContentStreamActive && _sfContentBuf.length >= 40) {
                if (onStreamEvent) {
                  onStreamEvent('file-content-token', _sfContentBuf);
                  _sfContentBuf = '';
                }
              }
            } else if (_sfFileWriteDetected && !_sfContentDone) {
              if (ch === '"' && /"content"\s*:\s*"$/.test(_sfFenceBuf)) {
                _sfContentStreamActive = true;
                const fpMatch = _sfFenceBuf.match(/"(?:filePath|path)"\s*:\s*"([^"]*)"/);
                _sfContentFilePath = fpMatch ? fpMatch[1] : '';
                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: _sfContentFilePath });
                }
                _sfStreamedFileWrites.add(_sfContentFilePath);
              }
            }
            if (!_sfFileWriteDetected && _sfFenceBuf.length > 30) {
              if ((/write_file|create_file|append_to_file/.test(_sfFenceBuf)) &&
                  (/"tool"\s*:/.test(_sfFenceBuf) || /"name"\s*:/.test(_sfFenceBuf))) {
                _sfFileWriteDetected = true;
              }
            }

            // Detect closing ``` — but NOT while inside the content string
            if (_sfContentStreamActive || _sfContentEsc || _sfUnicodeCount > 0) {
              _sfFenceTickCount = 0;
            } else if (ch === '`') {
              _sfFenceTickCount++;
            } else {
              if (_sfFenceTickCount >= 3) {
                // Closing fence found — flush any pending content
                if (_sfContentStreamActive && onStreamEvent) {
                  if (_sfContentBuf) {
                    onStreamEvent('file-content-token', _sfContentBuf);
                    _sfContentBuf = '';
                  }
                  onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _sfContentFilePath });
                  _sfContentStreamActive = false;
                }
                if (/"tool"\s*:/.test(_sfFenceBuf) || /"name"\s*:/.test(_sfFenceBuf)) {
                  _sfFenceBuf = '';
                } else {
                  _sfFlushFence();
                }
                _sfInFence = false;
                _sfFileWriteDetected = false;
                _sfContentDone = false;
                _sfContentEsc = false;
                _sfLastCharWasNewlineOrStart = (ch === '\n' || ch === '\r');
                continue;
              }
              _sfFenceTickCount = 0;
            }
            continue;
          }

          // ── Normal mode ──
          if (!_sfActive) {
            // Detect opening ``` at line start
            if (ch === '`' && _sfLastCharWasNewlineOrStart) {
              _sfFenceTickCount++;
              if (_sfFenceTickCount >= 3) {
                _sfInFence = true;
                _sfFenceBuf = '```';
                _sfFenceTickCount = 0;
                _sfFenceStreamPlain = false;
                _sfFencePlainTick = 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 ──
          // When inside a confirmed file-write tool call, intercept the "content"
          // field value and stream decoded characters to file-content-token events.
          if (_sfContentStreamActive) {
            if (_sfUnicodeCount > 0) {
              _sfUnicodeChars += ch;
              _sfUnicodeCount--;
              if (_sfUnicodeCount === 0) {
                try { _sfContentBuf += String.fromCharCode(parseInt(_sfUnicodeChars, 16)); }
                catch { _sfContentBuf += '\\u' + _sfUnicodeChars; }
              }
            } else if (_sfContentEsc) {
              let decoded;
              switch (ch) {
                case 'n': decoded = '\n'; break;
                case 't': decoded = '\t'; break;
                case 'r': decoded = '\r'; break;
                case '"': decoded = '"'; break;
                case '\\': decoded = '\\'; break;
                case '/': decoded = '/'; break;
                case 'b': decoded = '\b'; break;
                case 'f': decoded = '\f'; break;
                case 'u': _sfUnicodeCount = 4; _sfUnicodeChars = ''; decoded = null; break;
                default: decoded = ch;
              }
              _sfContentEsc = false;
              if (decoded !== null) _sfContentBuf += decoded;
            } else if (ch === '\\') {
              _sfContentEsc = true;
            } else if (ch === '"') {
              _sfContentStreamActive = false;
              _sfContentDone = true;
              if (_sfContentBuf && onStreamEvent) {
                onStreamEvent('file-content-token', _sfContentBuf);
                _sfContentBuf = '';
              }
              if (onStreamEvent) {
                onStreamEvent('file-content-end', { filePath: _sfContentFilePath, fileKey: _sfContentFilePath });
              }
            } else {
              _sfContentBuf += ch;
            }
            if (_sfContentStreamActive && _sfContentBuf.length >= 40) {
              if (onStreamEvent) {
                onStreamEvent('file-content-token', _sfContentBuf);
                _sfContentBuf = '';
              }
            }
          } else if (_sfConfirmed && _sfFileWriteDetected && !_sfContentDone) {
            if (ch === '"' && /"content"\s*:\s*"$/.test(_sfBuf)) {
              _sfContentStreamActive = true;
              const fpMatch = _sfBuf.match(/"(?:filePath|path)"\s*:\s*"([^"]*)"/);
              _sfContentFilePath = fpMatch ? fpMatch[1] : '';
              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: _sfContentFilePath });
              }
              _sfStreamedFileWrites.add(_sfContentFilePath);
            }
          }
          if (_sfConfirmed && !_sfFileWriteDetected && _sfBuf.length > 15) {
            if (/write_file|create_file|append_to_file/.test(_sfBuf)) {
              _sfFileWriteDetected = true;
            }
          }

          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 (/"tool"\s*:/.test(_sfBuf) || /"name"\s*:\s*"[^"]*"/.test(_sfBuf)) {
              _sfConfirmed = true;
            }
          }

          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 {
              _sfFlush();
            }
            _sfActive = false;
            _sfConfirmed = false;
            _sfFileWriteDetected = false;
            _sfContentDone = false;
            _sfLastCharWasNewlineOrStart = false;
          }
        }
      };

      // Build common generation options
      const thinkBudget = options.thinkingBudget;
      const genOptions = {
        signal: this._abortController.signal,
        stopOnAbortSignal: true,
        temperature: options.temperature ?? 0.7,
        topP: options.topP,
        topK: options.topK,
        repeatPenalty: options.repeatPenalty ? { penalty: options.repeatPenalty } : undefined,
        contextShift: { strategy: this._contextShiftStrategy.bind(this) },
        onTextChunk: (chunk) => {
          fullResponse += chunk;
          if (logStreamChunks) log.debug('ChatTurnStream', `[${chatTurnId}]`, chunk);
          _sfProcessChunk(chunk);
          tokensSinceLastUsageReport++;
          if (onContextUsage && tokensSinceLastUsageReport >= 50) {
            tokensSinceLastUsageReport = 0;
            const used = this._sequence.nextTokenIndex;
            const total = this._context.contextSize;
            onContextUsage({ used, total });
          }
        },
        onResponseChunk: (chunk) => {
          if (chunk.type === 'segment' && chunk.text && onStreamEvent) {
            onStreamEvent('llm-thinking-token', chunk.text);
          }
        },
      };

      // 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,
        };
      }

      // GBNF grammar-based function calling removed — small models (under ~4B)
      // either ignore the grammar or loop indefinitely (see PAST_FAILURES.md Category 6).
      // Tool calls are parsed from raw model text via toolParser.parseToolCalls().

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

      // Generate response — model outputs text which may contain tool call JSON blocks
      let result = await this._chat.generateResponse(this._chatHistory, genOptions);
      console.log(`[ChatEngine] generateResponse returned: stopReason=${result.metadata?.stopReason}, responseLen=${result.response?.length || 0}`);
      log.info(
        'ChatTurn',
        `[${chatTurnId}] generateResponse stopReason=${result.metadata?.stopReason ?? '?'} responseLen=${result.response?.length ?? 0} total_fullResponse_chars=${fullResponse.length}`,
      );

      // Raw-text tool call loop: parse tool calls from model output, execute, continue
      // Idempotency ledger: tool+params → previous result. Prevents infinite loops
      // when the model repeatedly emits the same tool call across continuation rounds.
      const toolCallLedger = new Map();
      if (executeToolFn) {
        // Flush any buffered content from the streaming filter before parsing
        _sfFlush();
        _sfFlushFence();

        let roundStart = 0;
        let parsedCalls = parseToolCalls(fullResponse);
        if (parsedCalls.length > 0) {
          const { repaired } = repairToolCalls(parsedCalls, fullResponse);
          parsedCalls = filterWebWorkspaceToolConflict(repaired);
        }

        // Safety net: if the streaming filter missed any tool JSON (e.g., fenced blocks),
        // strip it from the UI now via llm-replace-last.
        if (parsedCalls.length > 0 && onStreamEvent) {
          const cleanText = stripToolCallText(fullResponse);
          if (cleanText.length < fullResponse.length) {
            onStreamEvent('llm-replace-last', { originalLength: fullResponse.length, replacement: cleanText });
          }
        }

        while (parsedCalls.length > 0) {
          log.info(
            'ChatTurn',
            `[${chatTurnId}] tool_round parsed=${parsedCalls.length} tools=${parsedCalls.map((c) => c.tool).join(',')}`,
          );

          // Notify UI so ToolCallCards appear for each tool call (spinner state)
          if (onStreamEvent) {
            onStreamEvent('tool-executing', parsedCalls.map(c => ({ tool: c.tool, params: c.params })));
          }

          const toolResultLines = [];
          let allCallsWereDuplicates = true;
          let failedCallCount = 0;
          const webSearchResults = [];

          for (const call of parsedCalls) {
            totalToolCalls++;

            // Build idempotency key from tool name + serialized params (excluding content for file writes)
            const ledgerParams = { ...call.params };
            if (ledgerParams.content && ledgerParams.content.length > 200) {
              ledgerParams.content = ledgerParams.content.substring(0, 200);
            }
            const ledgerKey = `${call.tool}:${JSON.stringify(ledgerParams)}`;

            if (toolCallLedger.has(ledgerKey)) {
              const prevResult = toolCallLedger.get(ledgerKey);
              console.log(`[ChatEngine] Idempotent skip: ${call.tool} already executed with same params`);
              log.info('ChatTurn', `[${chatTurnId}] tool_skip_duplicate ${call.tool}`);
              const prevStr = typeof prevResult === 'string' ? prevResult : JSON.stringify(prevResult);
              const truncPrev = prevStr.length > 300 ? prevStr.substring(0, 300) + '...' : prevStr;
              toolResultLines.push(`${call.tool}: ALREADY EXECUTED — previous result: ${truncPrev}`);

              if (onStreamEvent) {
                onStreamEvent('mcp-tool-results', [{ tool: call.tool, result: prevResult }]);
              }
              if (onToolCall) onToolCall({ name: call.tool, params: call.params, result: prevResult });
              continue;
            }
            allCallsWereDuplicates = false;

            console.log(`[ChatEngine] Tool call: ${call.tool}(${JSON.stringify(call.params).substring(0, 200)})`);
            log.info(
              'ChatTurn',
              `[${chatTurnId}] tool_exec ${call.tool} params=${JSON.stringify(_summarizeToolParamsForLog(call.params))}`,
            );

            // Emit file-content events for file write operations so the UI
            // can show a FileContentBlock with syntax highlighting
            const FILE_WRITE_OPS = new Set(['write_file', 'create_file', 'append_to_file']);
            if (FILE_WRITE_OPS.has(call.tool) && call.params?.content && onStreamEvent) {
              const filePath = call.params.filePath || call.params.path || '';
              if (!_sfStreamedFileWrites.has(filePath)) {
                const fileName = filePath.split(/[\\/]/).pop() || filePath;
                const ext = fileName.includes('.') ? fileName.split('.').pop().toLowerCase() : '';
                onStreamEvent('file-content-start', { filePath, fileName, language: ext, fileKey: filePath });
                onStreamEvent('file-content-token', call.params.content);
                onStreamEvent('file-content-end', { filePath, fileKey: filePath });
              }
            }

            let toolResult;
            try {
              toolResult = await executeToolFn(call.tool, call.params);
            } catch (toolErr) {
              toolResult = { success: false, error: toolErr.message };
            }

            toolCallLedger.set(ledgerKey, toolResult);

            if (toolResult && toolResult.success === false) failedCallCount++;
            if (call.tool === 'web_search' && toolResult?.success && Array.isArray(toolResult.results)) {
              for (const r of toolResult.results.slice(0, 2)) {
                if (r && typeof r.url === 'string' && r.url) webSearchResults.push(r.url);
              }
            }

            const resultStr = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
            console.log(`[ChatEngine] Tool result for ${call.tool}: ${resultStr.substring(0, 200)}${resultStr.length > 200 ? '...' : ''}`);
            log.info(
              'ChatTurn',
              `[${chatTurnId}] tool_result ${call.tool} ok=${toolResult?.success !== false} preview=${_truncateForLog(resultStr, chatToolLogLimit)}`,
            );
            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 }]);
            }

            let injectResult = resultStr;
            if (injectResult.length > MAX_TOOL_RESULT_INJECT_CHARS) {
              injectResult = injectResult.slice(0, MAX_TOOL_RESULT_INJECT_CHARS)
                + '\n[... result truncated by system for context size; use only text above]';
            }
            toolResultLines.push(`${call.tool}: ${injectResult}`);
          }

          // If every call in this round was a duplicate, we reached convergence on tool state.
          if (allCallsWereDuplicates) {
            console.warn(`[ChatEngine] No new tool state in this round — moving to synthesis`);
            log.warn('ChatTurn', `[${chatTurnId}] tool_round all_duplicate → synthesis continuation`);
            this._lastEvaluation = result.lastEvaluation;
            if (result.lastEvaluation?.cleanHistory) {
              this._chatHistory = result.lastEvaluation.cleanHistory;
            }
            this._chatHistory.push({ type: 'user', text: `[Tool Results]
No new tool state was produced in the previous round. Synthesize your final answer from the existing tool results. If specific required evidence is still missing, request only the minimal new tool call with new parameters.` });
            genOptions.lastEvaluationContextWindow = this._lastEvaluation ? {
              contextWindow: this._lastEvaluation.contextWindow,
              contextShiftMetadata: this._lastEvaluation.contextShiftMetadata,
            } : undefined;

            // Reset streaming filter state
            _sfBuf = ''; _sfDepth = 0; _sfActive = false; _sfConfirmed = false;
            _sfInStr = false; _sfEscaped = false; _sfLastCharWasNewlineOrStart = true;
            _sfInFence = false; _sfFenceBuf = ''; _sfFenceTickCount = 0;
            _sfFileWriteDetected = false; _sfContentStreamActive = false;
            _sfContentDone = false; _sfContentEsc = false; _sfContentBuf = '';
            _sfContentFilePath = ''; _sfUnicodeCount = 0; _sfUnicodeChars = '';

            roundStart = fullResponse.length;
            result = await this._chat.generateResponse(this._chatHistory, genOptions);
            console.log(`[ChatEngine] Final continuation (post-dedup): stopReason=${result.metadata?.stopReason}, responseLen=${result.response?.length || 0}`);
            log.info(
              'ChatTurn',
              `[${chatTurnId}] post_dedup_generate stopReason=${result.metadata?.stopReason ?? '?'} responseLen=${result.response?.length ?? 0}`,
            );
            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.
          const allCallsFailed = failedCallCount > 0 && failedCallCount === parsedCalls.length;

          // Carry discovered web URLs as plain context for the next reasoning step.
          let fetchDirective = '';
          if (webSearchResults.length > 0) {
            const urlList = webSearchResults.map((u, i) => `${i + 1}. ${u}`).join('\n');
            fetchDirective = `Relevant URLs from web_search:\n${urlList}\n\n`;
          }

          const toolResultsGrounding = allCallsFailed
            ? 'Tool execution in the previous round returned errors only. Diagnose from those errors and choose the next most direct corrective action.\n\n'
            : `Grounding: The JSON below is authoritative. ${fetchDirective}Use fetched page content when answering web questions.\n\n`;

          const injectionSuffix = allCallsFailed
            ? '\n\nContinue by choosing the next corrective step.'
            : '\n\nContinue from the results above and complete the user request.';

          const toolFeedbackText = `[Tool Results]\n${toolResultsGrounding}${toolResultLines.join('\n')}${injectionSuffix}`;
          this._chatHistory.push({ type: 'user', text: toolFeedbackText });
          log.info(
            'ChatTurn',
            `[${chatTurnId}] tool_feedback_injected_chars=${toolFeedbackText.length} preview=\n${_truncateForLog(toolFeedbackText, chatBodyLogLimit)}`,
          );

          genOptions.lastEvaluationContextWindow = this._lastEvaluation ? {
            contextWindow: this._lastEvaluation.contextWindow,
            contextShiftMetadata: this._lastEvaluation.contextShiftMetadata,
          } : undefined;

          // 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;
          _sfContentEsc = false;
          _sfContentBuf = '';
          _sfContentFilePath = '';
          _sfUnicodeCount = 0;
          _sfUnicodeChars = '';

          // Generate continuation — model sees tool results and can issue more tool calls
          roundStart = fullResponse.length;
          result = await this._chat.generateResponse(this._chatHistory, genOptions);
          console.log(`[ChatEngine] Continuation after tools: stopReason=${result.metadata?.stopReason}, responseLen=${result.response?.length || 0}`);
          log.info(
            'ChatTurn',
            `[${chatTurnId}] continuation_after_tools stopReason=${result.metadata?.stopReason ?? '?'} responseLen=${result.response?.length ?? 0} fullResponse_chars=${fullResponse.length}`,
          );

          // Flush streaming filter buffer before parsing new text
          _sfFlush();
          _sfFlushFence();

          // Parse only the NEW text from this round (avoid re-executing previous tool calls)
          const newText = fullResponse.substring(roundStart);
          parsedCalls = parseToolCalls(newText);
          if (parsedCalls.length > 0) {
            const { repaired } = repairToolCalls(parsedCalls, newText);
            parsedCalls = filterWebWorkspaceToolConflict(repaired);

            // Safety net cleanup for any missed tool JSON in new text
            if (onStreamEvent) {
              const cleanNewText = stripToolCallText(newText);
              if (cleanNewText.length < newText.length) {
                onStreamEvent('llm-replace-last', { originalLength: newText.length, replacement: cleanNewText });
              }
            }
          }
        }
      }

      this._lastEvaluation = result.lastEvaluation;
      if (result.lastEvaluation?.cleanHistory) {
        this._chatHistory = result.lastEvaluation.cleanHistory;
      }
      const stopReason = result.metadata?.stopReason || 'natural';

      if (totalToolCalls > 0) {
        console.log(`[ChatEngine] Generation complete. Tool calls: ${totalToolCalls}, stop reason: ${stopReason}`);
      }

      log.info(
        'ChatTurn',
        `[${chatTurnId}] complete stopReason=${stopReason} toolCalls=${totalToolCalls} assistant_chars=${fullResponse.length}`,
      );
      log.info(
        'ChatTurn',
        `[${chatTurnId}] assistant_output_preview=\n${_truncateForLog(fullResponse, chatBodyLogLimit)}`,
      );

      if (onComplete) onComplete(fullResponse);
      return { text: fullResponse, stopReason, toolCallCount: totalToolCalls };
    } catch (err) {
      log.error('ChatTurn', `[${chatTurnId}] error`, err?.message || err);
      if (err.name === 'AbortError' || this._abortController?.signal?.aborted) {
        log.warn(
          'ChatTurn',
          `[${chatTurnId}] cancelled partial_chars=${fullResponse.length} partial_preview=\n${_truncateForLog(fullResponse, chatBodyLogLimit)}`,
        );
        return { text: fullResponse, stopReason: 'cancelled', toolCallCount: totalToolCalls };
      }
      throw err;
    } finally {
      if (generationTimer) clearTimeout(generationTimer);
      this._abortController = null;
    }
  }

  cancelGeneration(reason) {
    if (this._abortController) {
      this._abortController.abort(reason || 'cancelled');
    }
  }

  async resetSession() {
    this._chatHistory = [{ type: 'system', text: SYSTEM_PROMPT }];
    this._lastEvaluation = null;
    if (this._sequence) {
      try { this._sequence.clearHistory(); } catch {}
    }
  }

  getStatus() {
    return {
      isReady: this.isReady,
      isLoading: this.isLoading,
      modelInfo: this.modelInfo,
      currentModelPath: this.currentModelPath,
      gpuPreference: this.gpuPreference,
    };
  }

  async getGPUInfo() {
    try {
      const { execSync } = require('child_process');
      const csv = execSync(
        'nvidia-smi --query-gpu=name,memory.total,memory.used,memory.free,utilization.gpu,temperature.gpu --format=csv,noheader,nounits',
        { timeout: 5000 },
      ).toString().trim();
      const [name, memTotal, memUsed, memFree, utilGpu, temp] = csv.split(',').map(s => s.trim());
      return {
        name,
        memoryTotal: parseFloat(memTotal),
        memoryUsed: parseFloat(memUsed),
        memoryFree: parseFloat(memFree),
        gpuUtilization: parseFloat(utilGpu),
        temperature: parseFloat(temp),
      };
    } catch {
      return { name: 'Unknown', memoryTotal: 0, memoryUsed: 0, memoryFree: 0, gpuUtilization: 0, temperature: 0 };
    }
  }

  async dispose() {
    await this._dispose();
    this.isReady = false;
    this.modelInfo = null;
    this.currentModelPath = null;
    this.emit('status', { state: 'idle', message: 'Model unloaded' });
  }

  async _dispose() {
    try { if (this._sequence) this._sequence.dispose(); } catch {}
    try { if (this._context) await this._context.dispose(); } catch {}
    try { if (this._model) await this._model.dispose(); } catch {}
    this._sequence = null;
    this._context = null;
    this._model = null;
    this._chat = null;
    this._chatHistory = [];
    this._lastEvaluation = null;
  }

  _contextShiftStrategy({ chatHistory, maxTokensCount, tokenizer }) {
    if (chatHistory.length <= 2) return { chatHistory, metadata: { droppedCount: 0 } };

    const tokenize = (text) => {
      try { return tokenizer.tokenize(String(text || ''), false).length; }
      catch { return Math.ceil(String(text || '').length / 3); }
    };

    const getItemText = (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 '';
    };

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

    const budget = Math.floor(maxTokensCount * 0.85);
    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, truncate lastItem (keeps end)
    if (chatHistory.length > 1 && systemTokens + lastItemTokens > budget) {
      const availableForLastItem = budget - systemTokens - 20;
      if (availableForLastItem > 100) {
        const fullText = getItemText(lastItem);
        const isToolOrSystemInject = /^\[(?:Tool Results|System)\]/i.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'})`);
      }
    }

    // Pure sliding window: keep most recent messages that fit, no pinning
    let used = systemTokens + lastItemTokens;
    const keptIndices = new Set();

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

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

    console.log(`[ChatEngine] Context shift: kept ${keptIndices.size} items, dropped ${droppedCount}. Budget: ${budget}, used: ${used}`);
    return { chatHistory: newHistory, metadata: { droppedCount } };
  }

  _buildToolPrompt(functions) {
    const toolLines = Object.entries(functions).map(([name, def]) => {
      return `- ${name}: ${def.description || 'No description'}`;
    });
    return `\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, 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 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 and fetch_webpage as needed, and base conclusions on fetched evidence.\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.`;
  }

  _getNodeLlamaCppPath() {
    try {
      return require.resolve('node-llama-cpp');
    } catch {
      return path.join(__dirname, '..', 'node_modules', 'node-llama-cpp', 'dist', 'index.js');
    }
  }

  /**
   * 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) {
    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,
      };
    }
    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',
  // Memory
  'save_memory', 'get_memory', 'list_memories',
  // Planning
  'write_todos', 'update_todo',
]);

module.exports = { ChatEngine, buildEngineLoadSettings };