@semalt-ai/code 1.8.0 → 1.8.3

package/lib/agent.js

@@ -2,8 +2,12 @@
 
 const { logToolCall } = require('./audit');
 const { Metrics } = require('./metrics');
-const { SYSTEM_PROMPT } = require('./prompts');
+const { getSystemPrompt } = require('./prompts');
 const { TAG_REGISTRY } = require('./constants');
+const { mapInvokeToCall } = require('./tools');
+const { UI_THEME } = require('./ui/theme');
+const { RST } = require('./ui/ansi');
+const { getCols: _getCols, repeatToWidth } = require('./ui/utils');
 
 class StreamParser {
   constructor(onToken, onTagOpen, onTagContent, onTagClose) {
@@ -40,14 +44,18 @@ class StreamParser {
         const tagRaw = this.buffer.slice(1, gtIdx).trim();
         const selfClose = tagRaw.endsWith('/');
         const tagBody = selfClose ? tagRaw.slice(0, -1).trim() : tagRaw;
-        const spaceIdx = tagBody.search(/\s/);
-        const tagName = (spaceIdx === -1 ? tagBody : tagBody.slice(0, spaceIdx)).toLowerCase();
-        const attrStr = spaceIdx === -1 ? '' : tagBody.slice(spaceIdx + 1);
+        // Split on whitespace OR `=` so both MiniMax-style `<parameter name="x">`
+        // and Qwen3-Coder `<parameter=x>` resolve to the same tagName.
+        const delimIdx = tagBody.search(/[\s=]/);
+        const tagName = (delimIdx === -1 ? tagBody : tagBody.slice(0, delimIdx)).toLowerCase();
+        const attrStr = delimIdx === -1 ? '' : tagBody.slice(delimIdx + 1);
 
         const attrs = {};
-        const attrRe = /(\w+)="([^"]*)"/g;
+        const attrReDouble = /(\w+)="([^"]*)"/g;
+        const attrReSingle = /(\w+)='([^']*)'/g;
         let m;
-        while ((m = attrRe.exec(attrStr)) !== null) attrs[m[1]] = m[2];
+        while ((m = attrReDouble.exec(attrStr)) !== null) attrs[m[1]] = m[2];
+        while ((m = attrReSingle.exec(attrStr)) !== null) attrs[m[1]] = m[2];
 
         this.buffer = this.buffer.slice(gtIdx + 1);
 
@@ -70,11 +78,37 @@ class StreamParser {
       } else {
         const closing = '</' + this.insideTag + '>';
         const closeIdx = this.buffer.toLowerCase().indexOf(closing);
+        const entry = TAG_REGISTRY[this.insideTag];
+        const streamInner = entry && entry.type === 'final';
         if (closeIdx === -1) {
-          this.tagContent += this.buffer;
-          this.buffer = '';
+          if (streamInner) {
+            // Emit content live through onToken, but hold back any trailing
+            // substring that could be a prefix of the closing tag (chunk
+            // boundary splitting `</final_answer>` into e.g. `</fin` + `al…`).
+            const lowBuf = this.buffer.toLowerCase();
+            const lowClose = closing;
+            let safeUpTo = this.buffer.length;
+            const ltIdx = lowBuf.lastIndexOf('<');
+            if (ltIdx !== -1) {
+              const tail = lowBuf.slice(ltIdx);
+              if (lowClose.startsWith(tail)) safeUpTo = ltIdx;
+            }
+            if (safeUpTo > 0) {
+              const emit = this.buffer.slice(0, safeUpTo);
+              this.onToken(emit);
+              this.tagContent += emit;
+              this.buffer = this.buffer.slice(safeUpTo);
+            }
+          } else {
+            this.tagContent += this.buffer;
+            this.buffer = '';
+          }
           break;
         }
+        if (streamInner) {
+          const emit = this.buffer.slice(0, closeIdx);
+          if (emit) this.onToken(emit);
+        }
         this.tagContent += this.buffer.slice(0, closeIdx);
         this.buffer = this.buffer.slice(closeIdx + closing.length);
         this.onTagContent(this.insideTag, this.tagContent);
@@ -99,7 +133,7 @@ function cleanAssistantContent(raw) {
   }
 
   for (const [tag, entry] of Object.entries(TAG_REGISTRY)) {
-    if (entry.type === 'strip') {
+    if (entry.type === 'strip' || entry.type === 'final') {
       // Strip only the wrapper tags; keep the inner content
       text = text.replace(new RegExp(`<${tag}[^>]*>`, 'gi'), '');
       text = text.replace(new RegExp(`<\\/${tag}>`, 'gi'), '');
@@ -112,13 +146,142 @@ function cleanAssistantContent(raw) {
     }
   }
 
-  text = text.replace(/<\/?[a-zA-Z_][a-zA-Z0-9_]*(\s[^>]*)?>/g, '');
-  text = text.replace(/\n{2,}/g, '\n');
-
   return text.trim();
 }
 
-function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agentExecFile, ui }) {
+function estimateTokens(text) {
+  return Math.floor((text || '').length / 4);
+}
+
+function detectFormat(reply, toolCalls) {
+  if (!reply || !reply.trim()) return 'empty';
+  if (/<(minimax:tool_call|qwen:tool_call|tool_call|function_call)\b/i.test(reply)) return 'tool_call';
+  if (toolCalls && toolCalls.length > 0) return 'command';
+  return 'text';
+}
+
+// Spot known-tag names that are present in the reply but didn't produce any
+// parsed tool calls. Common culprits are attribute-required tags (create_file,
+// write_file, etc.) emitted without the `path` attribute, usually because the
+// model put nonsense like `<attrs: path=...>` inside the body. Returning a
+// specific hint lets the agent loop push a corrective user message and keep
+// going instead of silently stalling.
+function detectMalformedTags(text) {
+  const issues = [];
+  const PATH_REQUIRED = ['create_file', 'write_file', 'append_file'];
+  for (const tag of PATH_REQUIRED) {
+    const re = new RegExp(`<${tag}\\b([^>]*)>`, 'g');
+    for (const m of text.matchAll(re)) {
+      const attrs = m[1] || '';
+      if (!/\bpath\s*=\s*['"]/.test(attrs)) {
+        issues.push({
+          tag,
+          hint: `Use <${tag} path="/absolute/path">FILE CONTENT HERE</${tag}>. Put the path as a quoted attribute on the opening tag, and the actual file contents between the tags — not a nested pseudo-tag.`,
+        });
+      }
+    }
+  }
+  // Deduplicate by tag so we don't spam the model with the same hint per occurrence.
+  const seen = new Set();
+  return issues.filter((i) => (seen.has(i.tag) ? false : (seen.add(i.tag), true)));
+}
+
+function previewCommand(call) {
+  if (!call) return 'NONE — CLIENT WILL STALL';
+  const tag = call[0] || 'unknown';
+  const arg = call[1] || '';
+  const oneLine = String(arg).replace(/\s+/g, ' ').trim();
+  const trimmed = oneLine.length > 80 ? oneLine.slice(0, 77) + '...' : oneLine;
+  return trimmed ? `<${tag}> ${trimmed}` : `<${tag}>`;
+}
+
+function formatDebugBlock(sections) {
+  // The debug block is rendered as a tool-output message in the TUI. Chat
+  // history indents output by 5 cols; account for that so the frame still
+  // reaches the visible right edge instead of wrapping.
+  const totalW = Math.max(40, _getCols());
+  const frameW = Math.max(20, totalW - 7);
+  const H = UI_THEME.muted;       // frame glyphs
+  const L = UI_THEME.info;         // block label ("DEBUG TOOL RESULTS")
+  const S = UI_THEME.subtle;       // iteration tag, secondary text
+  const K = UI_THEME.accent;       // section-header bullets ("▸ SUMMARY")
+  const W = UI_THEME.warning;      // warning markers
+
+  const header = sections.title || 'DEBUG';
+  const iter = `[iteration ${sections.iteration}]`;
+
+  const out = [];
+  // Top frame: " LABEL [iteration N] ═════… " — fills to width.
+  const headPrefix = `${H}══ ${RST}${L}${header}${RST} ${S}${iter}${RST} `;
+  const headVisible = 4 + header.length + 1 + iter.length + 1; // "══ " + label + " " + iter + " "
+  out.push(`${headPrefix}${H}${repeatToWidth('═', frameW, headVisible)}${RST}`);
+
+  const pushSection = (title) => out.push(`${K}▸ ${RST}${L}${title}${RST}`);
+
+  for (const [title, rows] of sections.blocks) {
+    pushSection(title);
+    const width = Math.max(...rows.map((r) => r[0].length));
+    for (const [k, v] of rows) {
+      const val = (v === undefined || v === null) ? '—' : String(v);
+      out.push(`  ${S}${k.padEnd(width + 2)}${RST}${val}`);
+    }
+    out.push('');
+  }
+  if (sections.raw !== undefined) {
+    pushSection('RAW RESPONSE');
+    out.push(sections.raw ? sections.raw : `${S}(empty)${RST}`);
+    out.push('');
+    if (sections.rawFooter && sections.rawFooter.length) {
+      pushSection('STREAM FOOTER');
+      const width = Math.max(...sections.rawFooter.map((r) => r[0].length));
+      for (const [k, v] of sections.rawFooter) {
+        const val = (v === undefined || v === null) ? '—' : String(v);
+        out.push(`  ${S}${k.padEnd(width + 2)}${RST}${val}`);
+      }
+      out.push('');
+    }
+  }
+  if (sections.entries && sections.entries.length) {
+    for (const entry of sections.entries) {
+      pushSection(entry.title);
+      if (entry.rows) {
+        const width = Math.max(...entry.rows.map((r) => r[0].length));
+        for (const [k, v] of entry.rows) {
+          const val = (v === undefined || v === null) ? '—' : String(v);
+          out.push(`  ${S}${k.padEnd(width + 2)}${RST}${val}`);
+        }
+      }
+      if (entry.body !== undefined) {
+        const body = entry.body === '' ? `${S}(empty)${RST}` : entry.body;
+        for (const line of String(body).split('\n')) out.push('    ' + line);
+      }
+      out.push('');
+    }
+  }
+  if (sections.warnings && sections.warnings.length) {
+    pushSection('WARNINGS');
+    for (const w of sections.warnings) out.push(`  ${W}⚠ ${w}${RST}`);
+    out.push('');
+  }
+  // Bottom frame: plain full-width rule in muted.
+  out.push(`${H}${repeatToWidth('═', frameW)}${RST}`);
+  return out.join('\n');
+}
+
+function truncateForDebug(text, maxLines = 40, maxChars = 2000) {
+  if (text === undefined || text === null) return '';
+  let s = String(text);
+  if (s.length > maxChars) {
+    s = s.slice(0, maxChars) + `\n… [truncated, ${String(text).length - maxChars} more chars]`;
+  }
+  const lines = s.split('\n');
+  if (lines.length > maxLines) {
+    return lines.slice(0, maxLines).join('\n') + `\n… [truncated, ${lines.length - maxLines} more lines]`;
+  }
+  return s;
+}
+
+function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agentExecFile, ui, getConfig }) {
   const { BOLD, FG_DARK, FG_GRAY, FG_TEAL, FG_YELLOW, RST, THEME, getCols } = ui;
 
   function formatFileResult(call, result) {
@@ -140,20 +303,8 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
       case 'file_stat':
         return `Stat ${result.path}: size=${result.size_kb} KB, mtime=${result.mtime}, type=${result.type}, mode=${result.mode}`;
       case 'http_get': {
-        if (result.chunked) {
-          return `HTTP GET ${args[0]} (${result.status_code}) [Part 1/${result.total_parts}]:\n${result.body}\n\n[Response is large and was split into ${result.total_parts} parts. Use <http_get_next key="${args[0]}"/> to retrieve the next part.]`;
-        }
         return `HTTP GET ${args[0]} (${result.status_code}):\n${result.body}`;
       }
-      case 'http_get_next': {
-        if (result.done && !result.body) {
-          return `http_get_next "${args[0]}": No more content available.`;
-        }
-        const more = result.done
-          ? ' [Final part]'
-          : `\n\n[Use <http_get_next key="${args[0]}"/> to retrieve part ${result.part + 1}/${result.total_parts}.]`;
-        return `HTTP content "${args[0]}" [Part ${result.part}/${result.total_parts}]:\n${result.body}${more}`;
-      }
       case 'ask_user':
         return `User answered "${result.question}": ${result.answer}`;
       case 'store_memory':
@@ -257,10 +408,6 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
         const raw = attrs.raw || '';
         return formatFileResult(['http_get', url, raw], await agentExecFile('http_get', url, raw));
       }
-      case 'http_get_next': {
-        const key = attrs.key || content;
-        return formatFileResult(['http_get_next', key], await agentExecFile('http_get_next', key));
-      }
       case 'ask_user': {
         const q = attrs.question || content;
         return formatFileResult(['ask_user', q], await agentExecFile('ask_user', q));
@@ -295,9 +442,9 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
       return;
     }
 
-    if (entry.type === 'strip') return;
+    if (entry.type === 'strip' || entry.type === 'final') return;
 
-    // Tool execution happens in the toolCalls loop after streaming; handleTag only handles visual/strip.
+    // Tool execution happens in the toolCalls loop after streaming; handleTag only handles visual/strip/final.
   }
 
   async function runAgentLoop(messages, model, maxIterations = Infinity, tokenLimit = null, opts = {}) {
@@ -312,9 +459,32 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
     const isAborted = getAbortFlag || (() => false);
     const cb = callbacks;
     const metrics = new Metrics(tokenLimit);
-    const activeSystemPrompt = overrideSystemPrompt !== null ? overrideSystemPrompt : SYSTEM_PROMPT;
     const mode = overrideMode || 'system_role';
 
+    // Route debug blocks to the UI callback when present (interactive TUI mode
+    // overwrites stderr with redraws, losing the output). Fall back to stderr
+    // for one-shot/non-TTY flows where there's no UI to host the block.
+    const emitDebug = (block) => {
+      if (typeof cb.onDebug === 'function') cb.onDebug(block);
+      else process.stderr.write('\n' + block + '\n');
+    };
+
+    // Resolve native_tools from the active profile (matched by api_base+model).
+    // Fallback to true if no matching profile — mirrors config-normalization default.
+    const _cfg = typeof getConfig === 'function' ? getConfig() : {};
+    const _profile = Array.isArray(_cfg.models)
+      ? _cfg.models.find((p) => p && p.api_base === _cfg.api_base && p.model === model)
+      : null;
+    const nativeTools = _profile && _profile.native_tools === false ? false : true;
+
+    const activeSystemPrompt = overrideSystemPrompt !== null ? overrideSystemPrompt : getSystemPrompt(nativeTools);
+
+    // Response contract: every model response must end with a tool call or
+    // <final_answer>...</final_answer>. Anything else is degraded — push a
+    // synthetic nudge and retry, capped to prevent runaway loops.
+    const MAX_DEGRADED_RETRIES = 2;
+    let degradedRetries = 0;
+
     for (let iteration = 0; iteration < maxIterations; iteration++) {
       if (isAborted()) break;
       const linePrefix = `${FG_TEAL}${BOLD}◆ ${RST}`;
@@ -366,36 +536,96 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
           }
         : null;
 
-      if (debug) {
-        const header = `\n───── messages sent to agent (iteration ${iteration + 1}) ─────\n`;
-        const footer = `\n───── end messages ─────\n`;
-        process.stderr.write(header + JSON.stringify(messagesWithSystem, null, 2) + footer);
-      }
-
       const MAX_RETRIES = 3;
+      const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+      const NON_RETRYABLE_STATUS = new Set([400, 401, 403, 404, 413, 422]);
       let result = null;
       let lastApiErr = null;
 
-      for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
-        if (attempt === 1) {
-          callbacks.onRequestSent?.();
-        } else {
-          cb.onRetry?.(attempt, MAX_RETRIES);
-          await new Promise((r) => setTimeout(r, 1000));
-        }
-        try {
-          result = await chatStream(messagesWithSystem, {
-            model,
-            linePrefix: wrappedOnToken ? '' : linePrefix,
-            showThink,
-            onToken: wrappedOnToken,
-            silent: !!wrappedOnToken,
-          });
-          lastApiErr = null;
-          break;
-        } catch (err) {
-          lastApiErr = err;
+      // AbortController per iteration: watcher polls isAborted() every 50ms
+      // and flips controller.abort() as soon as the flag flips.
+      const controller = new AbortController();
+      const abortWatcher = setInterval(() => {
+        if (isAborted() && !controller.signal.aborted) controller.abort();
+      }, 50);
+
+      try {
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+          if (attempt === 1) {
+            callbacks.onRequestSent?.();
+          }
+          try {
+            result = await chatStream(messagesWithSystem, {
+              model,
+              nativeTools,
+              linePrefix: wrappedOnToken ? '' : linePrefix,
+              showThink,
+              onToken: wrappedOnToken,
+              silent: !!wrappedOnToken,
+              signal: controller.signal,
+              onTrim: (info) => {
+                // Setter (rather than re-reading config per iteration) keeps
+                // the Metrics instance authoritative: a 400-overflow discovery
+                // mid-loop immediately updates 85%-warning thresholds and the
+                // status bar without threading config access into agent.js.
+                if (info && info.reason === 'overflow-400' && typeof info.limit === 'number' && info.limit > 0) {
+                  metrics.setModelTokenLimit(info.limit);
+                }
+                if (cb.onError) {
+                  cb.onError({
+                    message: `Context trimmed (${info.reason}): ${info.dropped} message(s) dropped, kept ~${info.keptTokens} tokens (limit ${info.limit}).`,
+                    isWarning: true,
+                  });
+                }
+              },
+            });
+            lastApiErr = null;
+            break;
+          } catch (err) {
+            lastApiErr = err;
+            if (debug) {
+              const status = err.statusCode ? `HTTP ${err.statusCode}` : 'network error';
+              const body = err.rawBody !== undefined ? err.rawBody : (err.stack || err.message || String(err));
+              const block = formatDebugBlock({
+                iteration: iteration + 1,
+                blocks: [
+                  ['REQUEST', [
+                    ['model:', model],
+                    ['endpoint:', err.endpoint || '(unknown)'],
+                    ['timestamp:', new Date().toISOString()],
+                    ['native_tools:', nativeTools],
+                    ['attempt:', `${attempt}/${MAX_RETRIES}`],
+                  ]],
+                  ['RESPONSE', [
+                    ['status:', status],
+                    ['detail:', err.detail || ''],
+                  ]],
+                ],
+                raw: body || '(empty body)',
+                warnings: [`HTTP error on attempt ${attempt}/${MAX_RETRIES}: ${err.message}`],
+              });
+              emitDebug(block);
+            }
+            const sc = err.statusCode;
+            const retryable = !sc || RETRYABLE_STATUS.has(sc);
+            if (!retryable || NON_RETRYABLE_STATUS.has(sc)) break;
+            if (attempt >= MAX_RETRIES) break;
+            // Backoff: base 1000ms doubling (1s, 2s, 4s). For 429, honor
+            // Retry-After header when it's a plausible seconds value.
+            let delayMs = 1000 * Math.pow(2, attempt - 1);
+            if (sc === 429) {
+              const ra = err.responseHeaders && err.responseHeaders['retry-after'];
+              const raNum = ra !== undefined ? Number(ra) : NaN;
+              if (Number.isFinite(raNum) && raNum >= 0 && raNum <= 30) {
+                delayMs = Math.round(raNum * 1000);
+              }
+            }
+            cb.onRetry?.(attempt + 1, MAX_RETRIES);
+            await new Promise((r) => setTimeout(r, delayMs));
+          }
         }
+      } finally {
+        clearInterval(abortWatcher);
       }
 
       if (lastApiErr) {
@@ -407,51 +637,272 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
       const usage = result ? result.usage : null;
       metrics.endTurn(usage, model);
 
-      if (debug) {
-        const header = `\n───── raw ai response (iteration ${iteration + 1}) ─────\n`;
-        const footer = `\n───── end raw response ─────\n`;
-        process.stderr.write(header + (reply || '(empty)') + footer);
-      }
-
       if (cb.onMetricsUpdate) {
         cb.onMetricsUpdate({
           totalTokens: metrics.totalTokens(),
           contextTokens: metrics.contextTokens(),
           turns: metrics.turns.length,
+          tokenLimit: metrics.tokenLimitStatus(),
         });
       }
 
       const limitStatus = metrics.tokenLimitStatus();
-      if (limitStatus !== null && limitStatus.pct >= 85) {
+      if (limitStatus !== null && limitStatus.pct !== null && limitStatus.pct >= 85) {
         const warnMsg = `Context at ${limitStatus.pct}% of limit (${limitStatus.used}/${limitStatus.limit} tokens). Consider /compact.`;
         if (cb.onError) {
           cb.onError({ message: warnMsg, isWarning: true });
         } else {
+          // Non-TUI fallback (cb.onError is unset only for one-shot CLI
+          // commands like `cmdCode`, which don't run the shared live-region
+          // writer). Direct stdout write is safe here: no status-bar timer
+          // or bubble renderer is competing for stdout.
           process.stdout.write(
             `\n  ${THEME.warn}⚠ ${warnMsg}${THEME.reset}\n`
           );
         }
       }
 
-      if (!reply) break;
+      if (!reply) {
+        if (debug && result) {
+          const block = formatDebugBlock({
+            iteration: iteration + 1,
+            blocks: [
+              ['REQUEST', [
+                ['model:', result.request?.model || model],
+                ['endpoint:', result.endpoint || '(unknown)'],
+                ['timestamp:', new Date().toISOString()],
+                ['native_tools:', result.request?.native_tools ?? nativeTools],
+              ]],
+              ['RESPONSE', [
+                ['finish_reason:', result.finish_reason || '(unknown)'],
+                ['completion_tokens:', usage?.completion_tokens ?? 0],
+                ['latency_ms:', result.elapsed_ms ?? '?'],
+              ]],
+              ['PARSED', [
+                ['detected_format:', 'empty'],
+                ['commands_found:', 0],
+                ['first_command:', 'NONE — CLIENT WILL STALL'],
+              ]],
+            ],
+            raw: '',
+            warnings: ['Agent returned an empty response — connection to model may have dropped'],
+          });
+          emitDebug(block);
+        }
+        // Empty reply from the model — stream resolved with no content and no
+        // tool_calls. Most common causes: server-side disconnect mid-stream,
+        // context-window overflow that slipped past the 400/413 handler, or a
+        // model that returns only a stop token. Surface it so the user isn't
+        // left staring at an idle prompt.
+        if (cb.onError) {
+          const hint = iteration > 0 ? ' (after tool execution)' : '';
+          cb.onError({ message: `Agent returned an empty response${hint}. The connection to the model may have dropped — try again or /compact if context is large.`, isWarning: true });
+        }
+        break;
+      }
 
-      const toolCalls = extractToolCalls(reply);
+      // Native function-calling path: the model returned structured tool_calls.
+      // Convert them to the internal [action, ...args] tuple shape so downstream
+      // dispatch is unchanged, and remember the OpenAI id per call so results
+      // can be rooted back to their tool_call on the next turn.
+      const nativeToolCalls = Array.isArray(result?.toolCalls) ? result.toolCalls : [];
+      let toolCalls;
+      let nativeToolCallIds = [];
+      if (nativeToolCalls.length > 0) {
+        toolCalls = [];
+        for (const tc of nativeToolCalls) {
+          let args;
+          try {
+            args = tc.function?.arguments ? JSON.parse(tc.function.arguments) : {};
+          } catch (err) {
+            if (cb.onError) cb.onError({ message: `Failed to parse tool_call arguments for ${tc.function?.name || '(unknown)'}: ${err.message}`, isWarning: true });
+            continue;
+          }
+          const call = mapInvokeToCall(tc.function?.name, args);
+          if (call) {
+            toolCalls.push(call);
+            nativeToolCallIds.push(tc.id);
+          }
+        }
+      } else {
+        toolCalls = extractToolCalls(reply, { model });
+      }
+      const isNativeCall = nativeToolCalls.length > 0;
       const cleanedReply = cleanAssistantContent(reply);
+      // Protocol contract: a valid response ends with a tool call OR a
+      // <final_answer>...</final_answer> block. Anything else is degraded.
+      const hasFinal = /<final_answer\b[\s\S]*?<\/final_answer>/i.test(reply);
+
+      if (debug && result) {
+        const lastUserMsg = [...messagesWithSystem].reverse().find((m) => m.role === 'user');
+        const sysMsg = messagesWithSystem.find((m) => m.role === 'system');
+        const systemPromptTok = estimateTokens(sysMsg ? sysMsg.content : activeSystemPrompt);
+        const currentInputTok = estimateTokens(lastUserMsg ? lastUserMsg.content : '');
+        const historyTok = messagesWithSystem.reduce((sum, m) => {
+          if (m === sysMsg || m === lastUserMsg) return sum;
+          return sum + estimateTokens(m.content || '');
+        }, 0);
+        const promptTokens = usage && usage.prompt_tokens != null
+          ? usage.prompt_tokens
+          : systemPromptTok + historyTok + currentInputTok;
+        const completionTokens = usage && usage.completion_tokens != null
+          ? usage.completion_tokens
+          : estimateTokens(reply);
+        const thinkingTokens = result.reasoning ? estimateTokens(result.reasoning) : 0;
+        const visibleTokens = Math.max(completionTokens - thinkingTokens, 0);
+        const contextLimit = tokenLimit || null;
+        const ctxPct = contextLimit ? Math.round((promptTokens / contextLimit) * 100) : null;
+        const detected = detectFormat(reply, toolCalls);
+        const firstCmd = toolCalls.length > 0 ? previewCommand(toolCalls[0]) : previewCommand(null);
+        const toolTags = Object.entries(TAG_REGISTRY)
+          .filter(([, e]) => e.type === 'tool')
+          .map(([t]) => t);
+
+        const warnings = [];
+        if (result.finish_reason === 'length') warnings.push('finish_reason=length  → response truncated, increase max_tokens');
+        if (detected === 'tool_call' && toolCalls.length === 0) {
+          warnings.push('commands_found=0      → agent emitted no command, client will stall');
+        }
+        if (ctxPct !== null && ctxPct > 80) warnings.push(`context_used=${ctxPct}%    → approaching context limit`);
 
-      messages.push({ role: 'assistant', content: cleanedReply });
+        const block = formatDebugBlock({
+          iteration: iteration + 1,
+          blocks: [
+            ['REQUEST', [
+              ['model:', result.request?.model || model],
+              ['endpoint:', result.endpoint || '(unknown)'],
+              ['timestamp:', new Date().toISOString()],
+              ['native_tools:', result.request?.native_tools ?? nativeTools],
+            ]],
+            ['CONTEXT', [
+              ['total_messages:', messagesWithSystem.length],
+              ['system_prompt_tok:', systemPromptTok],
+              ['history_tok:', historyTok],
+              ['current_input_tok:', currentInputTok],
+              ['context_used:', contextLimit
+                ? `${promptTokens} / ${contextLimit}  (${ctxPct}%)`
+                : `${promptTokens} / unknown`],
+            ]],
+            ['PARAMETERS', [
+              ['max_tokens:', result.request?.max_tokens ?? '(default)'],
+              ['temperature:', result.request?.temperature ?? '(default)'],
+              ['stop_sequences:', JSON.stringify(result.request?.stop || [])],
+              ['reasoning_effort:', '(n/a)'],
+              ['tools_enabled:', `${toolTags.length} XML tags (via system prompt)`],
+            ]],
+            ['RESPONSE', [
+              ['finish_reason:', result.finish_reason || '(unknown)'],
+              ['completion_tokens:', completionTokens],
+              ['thinking_tokens:', thinkingTokens],
+              ['visible_tokens:', visibleTokens],
+              ['latency_ms:', result.elapsed_ms ?? '?'],
+            ]],
+            ['PARSED', [
+              ['detected_format:', detected],
+              ['commands_found:', toolCalls.length],
+              ['first_command:', firstCmd],
+            ]],
+          ],
+          raw: reply || '',
+          rawFooter: [
+            ['finish_reason:', result.finish_reason || '(unknown)'],
+            ['total_tokens:', result.usage_from_provider && result.usage
+              ? (result.usage.prompt_tokens || 0) + (result.usage.completion_tokens || 0)
+              : '(no usage)'],
+            ['content_chars:', (result.content || '').length],
+            ['reasoning_chars:', (result.reasoning_details || '').length],
+            ['tool_calls_seen:', result.tool_calls_count > 0 ? `yes (${result.tool_calls_count})` : 'no'],
+            ['native_mode:', isNativeCall ? `yes (${nativeToolCalls.length} call${nativeToolCalls.length === 1 ? '' : 's'})` : 'no'],
+          ],
+          warnings,
+        });
+        emitDebug(block);
+      }
+
+      // Detect mid-tag truncation: StreamParser tracks `insideTag` for the
+      // currently-unclosed tag. If it's still set after the stream settles,
+      // the response was cut off while inside a tool tag (hit max_tokens or
+      // a server-side cutoff). cleanAssistantContent strips the unclosed
+      // tag + trailing content, so extractToolCalls would find nothing and
+      // the loop would break silently. Surface it.
+      //
+      // When `cb.onToken` is unset (non-streaming UI), the parser was never
+      // fed — push the final reply through it once so `insideTag` reflects
+      // the terminal state.
+      if (!wrappedOnToken && reply) parser.push(reply);
+      const truncatedTag = parser.insideTag && TAG_REGISTRY[parser.insideTag]?.type === 'tool'
+        ? parser.insideTag
+        : null;
+      if (truncatedTag && cb.onError) {
+        cb.onError({ message: `Response truncated mid-<${truncatedTag}> tag — likely hit max_tokens or a server-side cutoff. Try again, shorten the request, or raise the model's max_tokens.`, isWarning: true });
+      }
+
+      const assistantMsg = { role: 'assistant', content: cleanedReply };
+      if (isNativeCall) assistantMsg.tool_calls = nativeToolCalls;
+      messages.push(assistantMsg);
       // When showThink is off and the turn has tool calls, suppress the text bubble —
       // pre-tool reasoning is noise, tool result bubbles already convey what happened.
       const displayReply = (!showThink && toolCalls.length > 0) ? '' : cleanedReply;
       if (cb.onAssistantMessage) cb.onAssistantMessage(displayReply);
 
-      if (toolCalls.length === 0) break;
+      if (toolCalls.length === 0) {
+        // Detect malformed known-tag syntax (e.g. <create_file> with no path
+        // attribute, usually paired with nonsense like <attrs: path=...> inside
+        // the body). Push a corrective feedback message and keep looping so
+        // the model self-corrects instead of silently stalling on the user.
+        const malformed = detectMalformedTags(reply);
+        if (malformed.length > 0) {
+          const hintBlock = malformed.map((m) => `- <${m.tag}>: ${m.hint}`).join('\n');
+          const summary = malformed.map((m) => `<${m.tag}>`).join(', ');
+          if (cb.onError) {
+            cb.onError({ message: `Detected malformed tool tag(s): ${summary}. Asking the model to retry with correct syntax.`, isWarning: true });
+          }
+          messages.push({
+            role: 'user',
+            content: `Your last response contained malformed tool tags that the parser could not execute:\n\n${hintBlock}\n\nRe-emit the tool calls using the exact syntax above. Do not nest pseudo-tags like <attrs: ...> inside the body.`,
+          });
+          continue;
+        }
+
+        if (hasFinal) {
+          // Model declared it is done — honor the protocol and terminate.
+          // An empty <final_answer></final_answer> is the model's choice;
+          // we don't police content.
+          degradedRetries = 0;
+          break;
+        }
+
+        // Protocol violation: neither a tool call nor a <final_answer>. Nudge
+        // the model to restate in-protocol, capped to prevent runaway loops.
+        if (degradedRetries >= MAX_DEGRADED_RETRIES) {
+          if (cb.onError) {
+            cb.onError({ message: `Agent violated the response contract after ${MAX_DEGRADED_RETRIES} retries — no tool call or <final_answer> block emitted. Stopping.`, isWarning: false });
+          }
+          break;
+        }
+        degradedRetries++;
+        if (cb.onError) {
+          cb.onError({ message: 'Response missing tool call or <final_answer> — nudging model to retry in-protocol.', isWarning: true });
+        }
+        messages.push({
+          role: 'user',
+          content: 'Your previous response contained neither a tool call nor a <final_answer> block, which violates the response contract. If you need to perform an action, emit the appropriate tool tag now. If you are done, wrap your reply in <final_answer>...</final_answer>. Do not describe intended actions in prose.',
+        });
+        continue;
+      }
+      // Non-degraded response (has tool calls) — reset the retry counter.
+      degradedRetries = 0;
       if (isAborted()) break;
 
       if (!cb.onToolStart) {
+        // Non-TUI fallback: only one-shot CLI commands leave cb.onToolStart
+        // unset. The shared live-region writer isn't running, so a direct
+        // write here can't interleave with a bubble/status redraw.
         process.stdout.write(`\n  ${FG_TEAL}◆${RST} ${FG_GRAY}Found ${toolCalls.length} action(s) to execute${RST}\n`);
       }
 
       const results = [];
+      const debugEntries = debug ? [] : null;
       let aborted = false;
 
       for (const call of toolCalls) {
@@ -471,6 +922,7 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
               const resultStr = `Command \`${arg}\`: Permission denied by user.`;
               if (cb.onToolEnd) cb.onToolEnd(tag, resultStr, ms);
               results.push(resultStr);
+              if (debugEntries) debugEntries.push({ tag, call, ms, status: 'denied', exitCode: null, result: resultStr });
               aborted = true;
               break;
             } else {
@@ -479,6 +931,14 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
               const resultStr = `Command \`${arg}\`:\nExit code: ${shellResult.exit_code}\n${out}`;
               if (cb.onToolEnd) cb.onToolEnd(tag, resultStr, ms);
               results.push(resultStr);
+              if (debugEntries) debugEntries.push({
+                tag,
+                call,
+                ms,
+                status: shellResult.exit_code === 0 ? 'ok' : 'nonzero_exit',
+                exitCode: shellResult.exit_code,
+                result: resultStr,
+              });
             }
             continue;
           }
@@ -490,12 +950,21 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
             const resultStr = `${tag} ${call[1] || ''}: Permission denied by user.`;
             if (cb.onToolEnd) cb.onToolEnd(tag, resultStr, ms);
             results.push(resultStr);
+            if (debugEntries) debugEntries.push({ tag, call, ms, status: 'denied', exitCode: null, result: resultStr });
             aborted = true;
             break;
           } else {
             const resultStr = formatFileResult(call, fileResult);
             if (cb.onToolEnd) cb.onToolEnd(tag, resultStr, ms);
             results.push(resultStr);
+            if (debugEntries) debugEntries.push({
+              tag,
+              call,
+              ms,
+              status: fileResult.error ? 'error' : 'ok',
+              exitCode: null,
+              result: resultStr,
+            });
           }
         } catch (err) {
           const ms = Date.now() - toolStart;
@@ -503,13 +972,60 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
           if (cb.onError) {
             cb.onError({ message: `Tool error (${tag}): ${err.message}`, isWarning: true });
           } else {
+            // Non-TUI fallback — see comment on the onToolStart branch above.
             process.stdout.write(`\n  ${THEME.warn}⚠ Tool error (${tag}): ${err.message}${THEME.reset}\n`);
           }
           logToolCall(tag, { args: call.slice(1) }, false, 'error');
           results.push(`${tag}: Error — ${err.message}`);
+          if (debugEntries) debugEntries.push({ tag, call, ms, status: 'exception', exitCode: null, result: `Error — ${err.message}` });
         }
       }
 
+      if (debug && debugEntries && debugEntries.length > 0) {
+        const totalMs = debugEntries.reduce((s, e) => s + (e.ms || 0), 0);
+        const statusCounts = debugEntries.reduce((acc, e) => {
+          acc[e.status] = (acc[e.status] || 0) + 1;
+          return acc;
+        }, {});
+        const statusSummary = Object.entries(statusCounts)
+          .map(([k, v]) => `${k}=${v}`)
+          .join(', ');
+
+        const entries = debugEntries.map((e, idx) => {
+          const argsPreview = (e.call || []).slice(1).map((a) => {
+            if (a === undefined || a === null) return '';
+            const s = String(a).replace(/\s+/g, ' ').trim();
+            return s.length > 120 ? s.slice(0, 117) + '...' : s;
+          }).filter((s) => s.length > 0).join(' │ ');
+          const rows = [
+            ['tag:', e.tag],
+            ['args:', argsPreview || '(none)'],
+            ['status:', e.status + (e.exitCode !== null && e.exitCode !== undefined ? ` (exit=${e.exitCode})` : '')],
+            ['latency_ms:', e.ms],
+          ];
+          return {
+            title: `TOOL ${idx + 1}/${debugEntries.length}`,
+            rows,
+            body: truncateForDebug(e.result),
+          };
+        });
+
+        const block = formatDebugBlock({
+          title: 'DEBUG TOOL RESULTS',
+          iteration: iteration + 1,
+          blocks: [
+            ['SUMMARY', [
+              ['tools_executed:', debugEntries.length],
+              ['total_latency_ms:', totalMs],
+              ['status_breakdown:', statusSummary],
+              ['aborted:', aborted ? 'yes' : 'no'],
+            ]],
+          ],
+          entries,
+        });
+        emitDebug(block);
+      }
+
       if (aborted) {
         const warnMsg = isAborted()
           ? 'Agent interrupted.'
@@ -517,24 +1033,37 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
         if (cb.onError) {
           cb.onError({ message: warnMsg, isWarning: true });
         } else {
+          // Non-TUI fallback — see comment above on the Found-actions path.
           process.stdout.write(`\n  ${FG_YELLOW}⚠${RST} ${FG_GRAY}${warnMsg}${RST}`);
         }
         // Push whatever results accumulated before the denial so the LLM has
         // context if the user asks to continue.
         if (results.length > 0) {
-          messages.push({
-            role: 'user',
-            content: `Tool execution results (partial — stopped after user denied an action):\n\n${results.join('\n\n')}`,
-          });
+          if (isNativeCall) {
+            for (let i = 0; i < results.length; i++) {
+              messages.push({ role: 'tool', tool_call_id: nativeToolCallIds[i], content: results[i] });
+            }
+          } else {
+            messages.push({
+              role: 'user',
+              content: `Tool execution results (partial — stopped after user denied an action):\n\n${results.join('\n\n')}`,
+            });
+          }
         }
         break;
       }
 
-      const feedback = results.join('\n\n');
-      messages.push({
-        role: 'user',
-        content: `Tool execution results:\n\n${feedback}\n\nContinue with the task. If everything is done, summarize what was accomplished.`,
-      });
+      if (isNativeCall) {
+        for (let i = 0; i < results.length; i++) {
+          messages.push({ role: 'tool', tool_call_id: nativeToolCallIds[i], content: results[i] });
+        }
+      } else {
+        const feedback = results.join('\n\n');
+        messages.push({
+          role: 'user',
+          content: `Tool execution results:\n\n${feedback}\n\nContinue with the task. If everything is done, summarize what was accomplished.`,
+        });
+      }
     }
 
     return { messages, metrics };
@@ -547,4 +1076,5 @@ function createAgentRunner({ chatStream, extractToolCalls, agentExecShell, agent
 
 module.exports = {
   createAgentRunner,
+  formatDebugBlock,
 };