@semalt-ai/code 1.8.4 → 1.8.5

package/lib/api.js

@@ -8,6 +8,63 @@ const { buildToolsSchema, isUIActive } = require('./tools');
 const { TOOL_SPECS } = require('./tool_specs');
 const writer = require('./ui/writer');
 const messages = require('./ui/messages');
+const dbg = require('./debug');
+
+// Strict precondition for any payload that includes role:tool messages or
+// assistant.tool_calls: every tool_call_id must reference a non-empty id from
+// a prior assistant tool_calls entry. Catches the upstream "tool result's tool
+// id() not found" 400 before it leaves the client and points at the exact
+// violating message instead of a cryptic provider error.
+function validateToolCallInvariant(msgs) {
+  const calledIds = new Set();
+  for (let idx = 0; idx < msgs.length; idx++) {
+    const m = msgs[idx];
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls)) {
+      for (let j = 0; j < m.tool_calls.length; j++) {
+        const tc = m.tool_calls[j];
+        if (!tc || !tc.id) {
+          throw new Error(
+            `Invalid tool_calls invariant: messages[${idx}] role=assistant tool_calls[${j}] has empty id`
+          );
+        }
+        calledIds.add(tc.id);
+      }
+    }
+  }
+  for (let idx = 0; idx < msgs.length; idx++) {
+    const m = msgs[idx];
+    if (m.role !== 'tool') continue;
+    if (!m.tool_call_id) {
+      const preview = String(m.content || '').slice(0, 80).replace(/\s+/g, ' ');
+      throw new Error(
+        `Invalid tool_calls invariant: messages[${idx}] role=tool has empty tool_call_id (content_preview="${preview}")`
+      );
+    }
+    if (!calledIds.has(m.tool_call_id)) {
+      throw new Error(
+        `Invalid tool_calls invariant: messages[${idx}] role=tool tool_call_id=${m.tool_call_id} has no matching prior assistant tool_calls`
+      );
+    }
+  }
+}
+
+function debugDumpMessages(msgs) {
+  dbg.logExtended('[messages dump before API request]');
+  for (let i = 0; i < msgs.length; i++) {
+    const m = msgs[i];
+    const callIds = Array.isArray(m.tool_calls)
+      ? m.tool_calls.map((t) => (t && t.id) || '<EMPTY>').join(',')
+      : '';
+    const toolCallId = m.tool_call_id !== undefined
+      ? ` tool_call_id=${m.tool_call_id || '<EMPTY>'}`
+      : '';
+    const tcs = callIds ? ` tool_calls=[${callIds}]` : '';
+    const contentLen = (m.content !== undefined && m.content !== null)
+      ? ` content_chars=${(m.content + '').length}`
+      : '';
+    dbg.logExtended(`  [${i}] role=${m.role}${toolCallId}${tcs}${contentLen}`);
+  }
+}
 
 function createApiClient({ getConfig, saveConfig, ui }) {
   const {
@@ -359,6 +416,8 @@ function createApiClient({ getConfig, saveConfig, ui }) {
     const endpoint = apiUrl('/v1/chat/completions');
 
     async function doRequest(msgs) {
+      if (dbg.isFile()) debugDumpMessages(msgs);
+      validateToolCallInvariant(msgs);
       const reqPayload = { ...payload, messages: msgs };
       const reqBody = JSON.stringify(reqPayload);
       const res = await httpRequest(endpoint, {
@@ -516,6 +575,11 @@ function createApiClient({ getConfig, saveConfig, ui }) {
             type: 'function',
             function: { name: t.name, arguments: t.arguments || '{}' },
           }));
+        dbg.logExtended(
+          `[tool_call finalize] acc_len=${toolCallAcc.length} ` +
+          `valid=${validToolCalls.length} nativeTools=${nativeTools} ` +
+          `acc=${JSON.stringify(toolCallAcc).slice(0, 400)}`
+        );
         if (!nativeTools) appendToolCallsXml();
         if (!silent) renderer.flush();
         // Fallback for endpoints that don't honor stream_options.include_usage:
@@ -564,6 +628,10 @@ function createApiClient({ getConfig, saveConfig, ui }) {
       res.setEncoding('utf8');
 
       res.on('data', (chunk) => {
+        if (dbg.isFile()) {
+          const raw = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+          dbg.logExtended(`[SSE raw] ${raw.slice(0, 500).replace(/\n/g, '\\n')}`);
+        }
         lineBuffer += chunk;
         const lines = lineBuffer.split('\n');
         lineBuffer = lines.pop();
@@ -572,11 +640,14 @@ function createApiClient({ getConfig, saveConfig, ui }) {
           if (!line.startsWith('data: ')) continue;
           const data = line.slice(6).trim();
           if (data === '[DONE]') {
+            dbg.logExtended(`[SSE event] [DONE]`);
             finalize();
             res.destroy();
             return;
           }
 
+          dbg.logExtended(`[SSE event] ${data.slice(0, 500)}`);
+
           try {
             const obj = JSON.parse(data);
             if (obj.usage && (obj.usage.prompt_tokens !== undefined || obj.usage.completion_tokens !== undefined)) {
@@ -619,15 +690,31 @@ function createApiClient({ getConfig, saveConfig, ui }) {
               }
             }
 
+            // Standard OpenAI tool_call streaming: the announcement chunk
+            // carries id + type + function.name with arguments="", and one or
+            // more follow-up chunks stream arguments deltas (no id/name).
+            // Process every chunk that has delta.tool_calls and patch in
+            // whichever fields are present — never gate slot creation or
+            // field updates on arguments being non-empty, or the announcement
+            // (which carries the only id/name) gets dropped.
             const toolCallsDelta = delta.tool_calls;
             if (Array.isArray(toolCallsDelta)) {
               for (const tc of toolCallsDelta) {
+                if (!tc || typeof tc !== 'object') continue;
                 const idx = typeof tc.index === 'number' ? tc.index : toolCallAcc.length;
-                const isNew = !toolCallAcc[idx];
-                if (isNew) toolCallAcc[idx] = { id: '', name: '', arguments: '' };
-                if (tc.id) toolCallAcc[idx].id = tc.id;
-                if (tc.function?.name) toolCallAcc[idx].name += tc.function.name;
-                if (tc.function?.arguments) toolCallAcc[idx].arguments += tc.function.arguments;
+                if (!toolCallAcc[idx]) {
+                  toolCallAcc[idx] = { id: '', name: '', arguments: '' };
+                }
+                const slot = toolCallAcc[idx];
+                if (tc.id) slot.id = tc.id;
+                const fnName = tc.function && tc.function.name;
+                if (typeof fnName === 'string' && fnName) slot.name = fnName;
+                const fnArgs = tc.function && tc.function.arguments;
+                if (typeof fnArgs === 'string') slot.arguments += fnArgs;
+                dbg.logExtended(
+                  `[tool_call acc] idx=${idx} id=${slot.id || '<empty>'} ` +
+                  `name=${slot.name || '<empty>'} args_len=${slot.arguments.length}`
+                );
               }
             }
 
@@ -649,7 +736,9 @@ function createApiClient({ getConfig, saveConfig, ui }) {
               fullText += content;
               tokenCount++;
             }
-          } catch {}
+          } catch (err) {
+            dbg.logExtended(`[SSE parse-error] ${err.message} :: ${data.slice(0, 200)}`);
+          }
         }
       });
 

package/lib/args.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const debug = require('./debug');
+
 function parseArgs(argv) {
   const opts = {};
   const positional = [];
@@ -62,6 +64,15 @@ function parseArgs(argv) {
       case '--debug':
         opts.debug = true;
         break;
+      case '--debug-file': {
+        const v = argv[++i];
+        if (!v || v.startsWith('-')) {
+          process.stderr.write(`Error: --debug-file requires a path argument.\n`);
+          process.exit(1);
+        }
+        opts.debugFile = v;
+        break;
+      }
       case '--system-prompt':
         opts.systemPromptFile = argv[++i];
         break;
@@ -71,6 +82,17 @@ function parseArgs(argv) {
     i++;
   }
 
+  if (opts.debug && opts.debugFile) {
+    process.stderr.write(
+      `Error: --debug and --debug-file are mutually exclusive.\n` +
+      `       Use --debug for inline debug output, or --debug-file <path>\n` +
+      `       for extended debug traces written to a file.\n`
+    );
+    process.exit(1);
+  }
+
+  debug.init({ debug: opts.debug, debugFile: opts.debugFile });
+
   return { opts, positional };
 }
 

package/lib/commands.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 
 const { CONFIG_PATH, DEFAULT_API_TIMEOUT_MS, TAG_REGISTRY } = require('./constants');
-const { configShow } = require('./config');
+const { configShow, isNativeToolsActive } = require('./config');
 const { getSystemPrompt } = require('./prompts');
 const { SessionStorage } = require('./storage');
 const { getSkippedOps, setUIActive } = require('./tools');
@@ -12,6 +12,63 @@ const { formatToolLine } = require('./ui/format');
 const writerModule = require('./ui/writer');
 const writer = writerModule;
 const msgs = require('./ui/messages');
+const dbg = require('./debug');
+
+// Drop assistant.tool_calls and role:tool messages whose ids don't pair up.
+// A loaded chat may contain role:tool with empty/missing tool_call_id (legacy
+// rows, dropped fields in transit) or assistant.tool_calls without a matching
+// tool response (truncated turn). Either side without its partner produces a
+// 400 from strict providers like MiniMax — the validator in api.js will throw
+// — so we strip both sides of the orphan pair before sending.
+function cleanOrphanedToolMessages(msgs) {
+  const calledIds = new Set();
+  const respondedIds = new Set();
+  for (const m of msgs) {
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls)) {
+      for (const tc of m.tool_calls) {
+        if (tc && tc.id) calledIds.add(tc.id);
+      }
+    } else if (m.role === 'tool' && m.tool_call_id) {
+      respondedIds.add(m.tool_call_id);
+    }
+  }
+  const paired = new Set();
+  for (const id of calledIds) if (respondedIds.has(id)) paired.add(id);
+
+  let droppedTool = 0;
+  let droppedAssistantCalls = 0;
+  let droppedAssistantMsgs = 0;
+  const out = [];
+  for (const m of msgs) {
+    if (m.role === 'tool') {
+      if (!m.tool_call_id || !paired.has(m.tool_call_id)) { droppedTool++; continue; }
+      out.push(m);
+    } else if (m.role === 'assistant' && Array.isArray(m.tool_calls)) {
+      const kept = m.tool_calls.filter((tc) => tc && tc.id && paired.has(tc.id));
+      droppedAssistantCalls += m.tool_calls.length - kept.length;
+      const hasContent = typeof m.content === 'string' && m.content.trim().length > 0;
+      if (kept.length === 0 && !hasContent) { droppedAssistantMsgs++; continue; }
+      const next = { ...m };
+      if (kept.length > 0) next.tool_calls = kept;
+      else delete next.tool_calls;
+      out.push(next);
+    } else {
+      out.push(m);
+    }
+  }
+  return { messages: out, droppedTool, droppedAssistantCalls, droppedAssistantMsgs };
+}
+
+function reconstructLoadedMessage(m) {
+  const msg = { role: m.role, content: m.content };
+  if (m.tool_call_id !== undefined && m.tool_call_id !== null && m.tool_call_id !== '') {
+    msg.tool_call_id = m.tool_call_id;
+  }
+  if (Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
+    msg.tool_calls = m.tool_calls;
+  }
+  return msg;
+}
 
 function formatTimeAgo(ts) {
   const diffMs = Date.now() - ts;
@@ -194,7 +251,11 @@ function createCommands({
     let messages = [];
     let currentChatId = null;
     let savedUpTo = 0;
-    let debugMode = !!opts.debug;
+    // The agent loop's per-iteration `formatDebugBlock` runs whenever any
+    // debug mode is active. In simple mode the block is rendered as a TUI
+    // chat bubble (cb.onDebug → addMessage). In file mode emitDebug routes
+    // the block to the debug file instead, keeping the TUI clean.
+    let debugMode = dbg.isActive();
 
     // Resolve system prompt override from --system-prompt file if provided
     let resolvedSystemPrompt = null;
@@ -284,7 +345,15 @@ function createCommands({
       if (currentChatId === null) return;
       const newMessages = messages.slice(savedUpTo).filter((m) => m.role !== 'system');
       if (!newMessages.length) return;
-      try { await dashboardSaveMessages(currentChatId, newMessages); savedUpTo = messages.length; } catch {}
+      try {
+        const resp = await dashboardSaveMessages(currentChatId, newMessages);
+        savedUpTo = messages.length;
+        if (resp && typeof resp.skipped_count === 'number' && resp.skipped_count > 0) {
+          msgs.sysWarn(`history save: ${resp.skipped_count} message(s) skipped by server`);
+        }
+      } catch (err) {
+        msgs.sysWarn(`history save failed: ${err && err.message ? err.message : String(err)}`);
+      }
     }
 
     function displayLoadedMessages(loadedMessages) {
@@ -295,7 +364,7 @@ function createCommands({
         const ts = m.created_at ? new Date(m.created_at) : (m.ts ? new Date(m.ts) : new Date());
 
         if (m.role === 'tool') {
-          chatHistory.addMessage({ role: 'tool', tag: 'tool', content: 'tool result', output: raw, ts });
+          chatHistory.addMessage({ role: 'tool', tag: 'tool', content: raw, ts });
           continue;
         }
 
@@ -304,7 +373,7 @@ function createCommands({
             .replace(/^Tool execution results[^\n]*\n+/, '')
             .replace(/\n+Continue with the task\.[\s\S]*$/, '')
             .trim();
-          chatHistory.addMessage({ role: 'tool', tag: 'tool', content: 'tool result', output: body || raw, ts });
+          chatHistory.addMessage({ role: 'tool', tag: 'tool', content: body || raw, ts });
           continue;
         }
 
@@ -313,6 +382,34 @@ function createCommands({
       }
     }
 
+    // After loading a saved chat (via --resume, /history, or /chats), the
+    // status bar has no API-reported prompt_tokens to display until the next
+    // turn completes — the indicator would sit at 0 until the user sends a
+    // follow-up. Seed it with a client-side estimate of the loaded messages
+    // using the same approxTokens estimator the live `addPendingTokens` path
+    // uses, then push it through `updateMetrics({contextTokens})` — the same
+    // setter agent.js wires up via cb.onMetricsUpdate. The next real turn
+    // overwrites this with the API's authoritative prompt_tokens.
+    function seedContextFromMessages() {
+      let total = 0;
+      for (const m of messages) {
+        if (typeof m.content === 'string') total += approxTokens(m.content);
+      }
+      statusBar.updateMetrics({ contextTokens: total });
+    }
+
+    function emitCleanupWarning(cleanup) {
+      if (cleanup.droppedTool === 0 && cleanup.droppedAssistantCalls === 0 && cleanup.droppedAssistantMsgs === 0) return;
+      const parts = [];
+      if (cleanup.droppedTool > 0) parts.push(`${cleanup.droppedTool} orphaned tool result(s)`);
+      if (cleanup.droppedAssistantCalls > 0) parts.push(`${cleanup.droppedAssistantCalls} dangling tool_call(s)`);
+      if (cleanup.droppedAssistantMsgs > 0) parts.push(`${cleanup.droppedAssistantMsgs} empty assistant message(s)`);
+      chatHistory.addMessage({
+        role: 'system',
+        content: `⚠ Loaded chat had ${parts.join(', ')}, cleaned up. The chat may be missing some context.`,
+      });
+    }
+
     // --resume: load previous chat
     if (opts.resume) {
       const resumeId = parseInt(opts.resume, 10);
@@ -320,12 +417,16 @@ function createCommands({
         try {
           const chatData = await dashboardGetChat(resumeId);
           const loaded = chatData && chatData.messages ? chatData.messages : [];
-          for (const m of loaded) messages.push({ role: m.role, content: m.content });
+          for (const m of loaded) messages.push(reconstructLoadedMessage(m));
+          const cleanup = cleanOrphanedToolMessages(messages);
+          messages = cleanup.messages;
           currentChatId = resumeId;
           savedUpTo = messages.length;
           const title = chatData.chat && chatData.chat.title ? chatData.chat.title : `#${resumeId}`;
           displayLoadedMessages(loaded);
           chatHistory.addMessage({ role: 'system', content: `✓ Resumed: ${title} (${loaded.length} messages)` });
+          emitCleanupWarning(cleanup);
+          seedContextFromMessages();
         } catch (error) {
           chatHistory.addMessage({ role: 'system', content: `✗ Could not resume chat: ${error.message}`, isError: true });
         }
@@ -470,7 +571,9 @@ function createCommands({
       if (type === 'history') {
         const loaded = storage.load(activeItems[idx].id);
         if (loaded) {
-          messages = (loaded.messages || []).filter((m) => m.role !== 'system');
+          const filtered = (loaded.messages || []).filter((m) => m.role !== 'system');
+          const cleanup = cleanOrphanedToolMessages(filtered);
+          messages = cleanup.messages;
           session = { id: loaded.id, created_at: loaded.created_at, model: loaded.model, messages, stats: loaded.stats || { total_tokens: 0, duration_sec: 0 } };
           currentChatId = null; savedUpTo = 0;
           if (loaded.model && loaded.model !== currentModel) {
@@ -481,16 +584,22 @@ function createCommands({
           }
           displayLoadedMessages(messages);
           chatHistory.addMessage({ role: 'system', content: `✓ Session loaded.  Model → ${currentModel}` });
+          emitCleanupWarning(cleanup);
+          seedContextFromMessages();
         }
       } else if (type === 'chats') {
         const selectedChat = activeItems[idx];
         try {
           const chatData = await dashboardGetChat(selectedChat.id);
           const loaded = chatData && chatData.messages ? chatData.messages : [];
-          messages = loaded.map((m) => ({ role: m.role, content: m.content }));
+          const reconstructed = loaded.map(reconstructLoadedMessage);
+          const cleanup = cleanOrphanedToolMessages(reconstructed);
+          messages = cleanup.messages;
           currentChatId = selectedChat.id; savedUpTo = messages.length;
           displayLoadedMessages(loaded);
           chatHistory.addMessage({ role: 'system', content: `✓ Resumed: ${selectedChat.title} (${loaded.length} messages)` });
+          emitCleanupWarning(cleanup);
+          seedContextFromMessages();
         } catch (err) {
           chatHistory.addMessage({ role: 'system', content: `✗ ${err.message}`, isError: true });
         }
@@ -767,7 +876,8 @@ function createCommands({
       }
 
       if (text === '/prompt') {
-        const activePrompt = resolvedSystemPrompt !== null ? resolvedSystemPrompt : getSystemPrompt();
+        const nativeTools = isNativeToolsActive(currentModel);
+        const activePrompt = resolvedSystemPrompt !== null ? resolvedSystemPrompt : getSystemPrompt(nativeTools);
         const src = resolvedSystemPrompt !== null ? `file: ${opts.systemPromptFile}` : 'built-in';
         const mode = getConfig().system_prompt_mode || 'system_role';
         chatHistory.addMessage({
@@ -810,9 +920,12 @@ function createCommands({
           tail = '\nNo audit log found.';
         }
 
+        const sink = dbg.isFile()
+          ? `file (${dbg.getMode()} mode)`
+          : 'inline chat history';
         chatHistory.addMessage({
           role: 'system',
-          content: `Debug output: ${debugMode ? 'ON' : 'OFF'} (raw messages, raw AI responses, raw HTTP errors → stderr)${tail}`,
+          content: `Debug output: ${debugMode ? 'ON' : 'OFF'} → ${sink}${tail}`,
         });
         return;
       }
@@ -895,6 +1008,21 @@ function createCommands({
           chatHistory.addMessage({ role: 'think', content });
           statusBar.update('streaming', 'Streaming response');
         },
+        onPermissionAsk: (tag, input) => {
+          // Status-bar update fires while the permission picker is open so
+          // the user can see what's pending in the side label, not just
+          // inside the modal. Mirrors the labels onToolStart uses post-grant
+          // — the next streaming/idle state will overwrite this when the
+          // picker closes (whether granted or denied).
+          const actionLabel = TAG_REGISTRY[tag]?.label || tag;
+          const short = input && input.length > 40 ? input.slice(0, 40) + '…' : (input || '');
+          const isDownload = tag === 'download' || tag === 'http_get';
+          if (isDownload) {
+            statusBar.update('waiting_download', `Waiting for download: ${short}`);
+          } else {
+            statusBar.update('tool', `${actionLabel}: ${short}`);
+          }
+        },
         onToolStart: (tag, input, ctx) => {
           const actionLabel = TAG_REGISTRY[tag]?.label || tag;
           const short = input && input.length > 40 ? input.slice(0, 40) + '…' : (input || '');
@@ -908,18 +1036,39 @@ function createCommands({
           // The render function is re-invoked by the writer on every
           // redraw so the pending line's elapsed time stays current with
           // the ticker cadence without an explicit refresh timer.
+          //
+          // ask_user is the only currently-blocking tool — it pauses the
+          // agent until the user responds via the modal. A ticking
+          // elapsed-time meter on a paused tool is misleading ("13s"
+          // suggests work is happening), and the per-tick redraw
+          // interacts badly with the open modal (see TECHNICAL_DEBT.md).
+          // Render once with no duration meta and freeze. Replace this
+          // name check with a category flag (e.g. blocking: true on the
+          // tool spec) if more blocking tools appear.
           if (ctx && ctx.id) {
-            writerModule.startActivity(ctx.id, (elapsedMs) => formatToolLine({
-              status: 'pending',
-              tag,
-              arg: input,
-              attrs: ctx.attrs,
-              durationMs: elapsedMs,
-            }));
+            if (tag === 'ask_user') {
+              const staticLine = formatToolLine({
+                status: 'pending',
+                tag,
+                arg: input,
+                attrs: ctx.attrs,
+                noDuration: true,
+              });
+              writerModule.startActivity(ctx.id, () => staticLine);
+            } else {
+              writerModule.startActivity(ctx.id, (elapsedMs) => formatToolLine({
+                status: 'pending',
+                tag,
+                arg: input,
+                attrs: ctx.attrs,
+                durationMs: elapsedMs,
+              }));
+            }
           }
         },
         onToolEnd: (tag, result, durationMs, ctx) => {
           const hasError = !!(ctx && ctx.error);
+          const isBlocking = tag === 'ask_user';
           const finalLine = formatToolLine({
             status: hasError ? 'failure' : 'success',
             tag,
@@ -928,6 +1077,7 @@ function createCommands({
             durationMs,
             meta: ctx ? ctx.meta : null,
             error: ctx ? ctx.error : null,
+            noDuration: isBlocking,
           });
           if (ctx && ctx.id) {
             writerModule.endActivity(ctx.id, finalLine);
@@ -1092,7 +1242,7 @@ function createCommands({
     let messages = [{ role: 'user', content: fullPrompt }];
     writer.scrollback(`  ${FG_GRAY}◆ ${model}${RST}`);
     const codeResult = await runAgentLoop(messages, model, undefined, null, {
-      debug: opts.debug || false,
+      debug: dbg.isActive(),
       systemPrompt: resolvedSystemPrompt,
       systemPromptMode: getConfig().system_prompt_mode || 'system_role',
     });

package/lib/config.js

@@ -111,6 +111,18 @@ function configSet(key, value) {
   return cfg;
 }
 
+// Resolves whether the active profile uses native function calling.
+// Defaults to true if no profile match is found (matches normalizeConfig
+// default and the agent.js lookup fallback).
+function isNativeToolsActive(model) {
+  const cfg = loadConfig();
+  if (!Array.isArray(cfg.models)) return true;
+  const profile = cfg.models.find(
+    (p) => p && p.api_base === cfg.api_base && p.model === model
+  );
+  return !(profile && profile.native_tools === false);
+}
+
 const REDACTED_KEYS = new Set(['api_key', 'auth_token']);
 
 function configShow(systemPromptOverride = null) {
@@ -132,6 +144,7 @@ function configShow(systemPromptOverride = null) {
 module.exports = {
   configSet,
   configShow,
+  isNativeToolsActive,
   loadConfig,
   normalizeConfig,
   saveConfig,

package/lib/debug.js

@@ -0,0 +1,106 @@
+'use strict';
+
+// Two mutually-exclusive debug modes, configured once at startup from the
+// CLI flags (--debug or --debug-file <path>).
+//
+//   off    — no debug output anywhere.
+//   simple — visible inline. Basic per-iteration info routed through
+//            writer.scrollback so the TUI keeps working (no SSE dumps,
+//            no per-chunk noise).
+//   file   — every debug call (basic AND extended) is written to a file.
+//            Nothing debug-related goes to stdout. The TUI stays clean.
+//
+// Two log functions with a clear semantic split:
+//
+//   log(line)         — "always-on" debug. Visible in simple mode (scrollback)
+//                       and file mode (file). Silent in off mode.
+//   logExtended(line) — extended traces (raw SSE, request bodies, delta
+//                       accumulators). Visible only in file mode.
+//
+// File-mode lines are formatted as `[ISO-timestamp] <line>\n` so they're
+// greppable and tail-friendly.
+
+const fs = require('fs');
+
+let mode = 'off';
+let fileStream = null;
+
+function init({ debug, debugFile } = {}) {
+  if (debug && debugFile) {
+    // Belt-and-braces: cli.js (args parser) errors out before this is ever
+    // reached. Throw rather than silently coerce so any internal misuse is
+    // surfaced loudly.
+    throw new Error('debug and debugFile are mutually exclusive');
+  }
+  if (debugFile) {
+    mode = 'file';
+    fileStream = fs.createWriteStream(debugFile, { flags: 'a' });
+    const ts = new Date().toISOString();
+    try {
+      fileStream.write(`\n[${ts}] [session] semalt-code debug session start pid=${process.pid}\n`);
+    } catch {}
+  } else if (debug) {
+    mode = 'simple';
+  } else {
+    mode = 'off';
+  }
+}
+
+function isActive()  { return mode !== 'off'; }
+function isSimple()  { return mode === 'simple'; }
+function isFile()    { return mode === 'file'; }
+function getMode()   { return mode; }
+
+function _writeFile(line) {
+  if (!fileStream) return;
+  const ts = new Date().toISOString();
+  try { fileStream.write(`[${ts}] ${line}\n`); } catch {}
+}
+
+// "Always-on" debug — visible in simple mode (scrollback) and file mode (file).
+// Silent in off mode. Multi-line input gets one timestamp per line in file mode
+// so each line stays greppable.
+function log(line) {
+  if (mode === 'off') return;
+  const s = String(line);
+  if (mode === 'simple') {
+    // Lazy-require to avoid a require cycle: writer pulls in this module
+    // for its own drift diagnostic.
+    const writer = require('./ui/writer');
+    writer.scrollback(s);
+  } else {
+    for (const l of s.split('\n')) _writeFile(l);
+  }
+}
+
+// Extended-only debug — visible in file mode only. Used for high-volume
+// per-chunk traces (raw SSE, request body dumps, accumulator state) that
+// would shred the TUI if printed inline.
+function logExtended(line) {
+  if (mode !== 'file') return;
+  const s = String(line);
+  for (const l of s.split('\n')) _writeFile(l);
+}
+
+function close() {
+  if (fileStream) {
+    try {
+      const ts = new Date().toISOString();
+      fileStream.write(`[${ts}] [session] end pid=${process.pid}\n`);
+      fileStream.end();
+    } catch {}
+    fileStream = null;
+  }
+  mode = 'off';
+}
+
+module.exports = {
+  init,
+  isActive,
+  isSimple,
+  isFile,
+  getMode,
+  log,
+  logExtended,
+  close,
+};