skyloom 1.13.5 → 1.13.7

package/src/cli/tui.ts

@@ -1,222 +1,228 @@
-/**
- * 天空织机 TUI — a polished *linear* terminal interface.
- *
- * Design note: the previous version tried to be a full-screen app, redrawing
- * the whole screen on every keystroke while the reply streamed linearly below
- * it — the two fought, the conversation never persisted, and hand-rolled
- * raw-mode editing mangled CJK width. This rewrite is linear (like Claude Code
- * / opencode): real readline line-editing + a CJK-aware wrapping stream
- * renderer. Robust, flicker-free, and it actually reads like a conversation.
- */
-
-import * as readline from "readline";
-import chalk from "chalk";
-import { agentTheme, PALETTE } from "../core/theme";
-
-const TUI_VERSION = (() => { try { return require("../../package.json").version; } catch { return ""; } })();
-
-export interface TUIContext {
-  agent: any;
-  agents: Map<string, any>;
-  model: string;
-  cost: string;
-  width: number;
-  height: number;
-}
-
-/* ── Slash commands (for tab-completion + the inline palette) ── */
-export const SLASH_COMMANDS: [string, string][] = [
-  ["/fog", "≋ 雾 · 探索洞察"],
-  ["/rain", "⸽ 雨 · 创造产出"],
-  ["/frost", "✱ 霜 · 精炼品质"],
-  ["/snow", "❉ 雪 · 架构规划"],
-  ["/dew", "∘ 露 · 可靠守护"],
-  ["/fair", "☼ 晴 · 情感陪伴"],
-  ["/help", "查看所有命令"],
-  ["/setup", "配置向导"],
-  ["/model", "模型信息"],
-  ["/cost", "费用统计"],
-  ["/status", "状态总览"],
-  ["/memory", "记忆状态"],
-  ["/sessions", "会话列表"],
-  ["/resume ", "恢复会话（序号/id）"],
-  ["/new", "开始新会话"],
-  ["/workspace", "工作空间"],
-  ["/compact", "压缩上下文"],
-  ["/clear", "清屏"],
-  ["/task ", "多 Agent 编排"],
-  ["/mcp", "MCP 服务器"],
-  ["/version", "版本信息"],
-  ["/quit", "退出"],
-];
-
-/* ════════════════════════════════════════
-   CJK-aware display width
-   ════════════════════════════════════════ */
-/** Visual columns occupied by a single code point (CJK / fullwidth = 2). */
-export function charWidth(cp: number): number {
-  if (cp === 0) return 0;
-  if (cp < 32 || (cp >= 0x7f && cp < 0xa0)) return 0; // control
-  // East-Asian wide / fullwidth ranges
-  if (
-    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
-    (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals, Kangxi, punctuation
-    (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana…CJK symbols
-    (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Ext A
-    (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified
-    (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
-    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
-    (cp >= 0xf900 && cp <= 0xfaff) || // CJK compat
-    (cp >= 0xfe10 && cp <= 0xfe19) ||
-    (cp >= 0xfe30 && cp <= 0xfe6f) || // CJK compat forms
-    (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth forms
-    (cp >= 0xffe0 && cp <= 0xffe6) ||
-    (cp >= 0x1f300 && cp <= 0x1faff) // emoji / pictographs
-  ) return 2;
-  return 1;
-}
-
-const ANSI_RE = /\x1b\[[0-9;]*m/g;
-
-/** Visual width of a string, ignoring ANSI color codes. */
-export function visualWidth(s: string): number {
-  let w = 0;
-  for (const ch of s.replace(ANSI_RE, "")) w += charWidth(ch.codePointAt(0) || 0);
-  return w;
-}
-
-/** Pad a string (containing ANSI) to a visual width. */
-export function padVisual(s: string, width: number): string {
-  const diff = width - visualWidth(s);
-  return diff > 0 ? s + " ".repeat(diff) : s;
-}
-
-/* ════════════════════════════════════════
-   Streaming renderer — word-wrap aware, CJK aware
-   ════════════════════════════════════════ */
-/**
- * Writes streamed text with a fixed left gutter, wrapping at the terminal
- * width. English wraps on word boundaries; CJK wraps per glyph. Color is
- * applied per flushed chunk so styling survives wrapping.
- */
-export class StreamRenderer {
-  private col = 0;
-  private word = "";
-  private atLineStart = true;
-  private out: NodeJS.WriteStream;
-  private gutter: string;
-  private maxCols: number;
-  private color: (s: string) => string;
-
-  constructor(out: NodeJS.WriteStream, opts?: { gutter?: string; color?: (s: string) => string }) {
-    this.out = out;
-    this.gutter = opts?.gutter ?? "  ";
-    this.color = opts?.color ?? ((s) => s);
-    const cols = out.columns || 80;
-    // content width excludes the gutter; clamp for readability
-    this.maxCols = Math.max(32, Math.min(cols - visualWidth(this.gutter) - 1, 96));
-  }
-
-  /** Lazily emit the left gutter at the start of each visual line. */
-  private startLine() { if (this.atLineStart) { this.out.write(this.gutter); this.atLineStart = false; } }
-  private newline() { this.out.write("\n"); this.atLineStart = true; this.col = 0; }
-
-  private flushWord() {
-    if (!this.word) return;
-    const w = visualWidth(this.word);
-    if (this.col > 0 && this.col + w > this.maxCols) this.newline();
-    this.startLine();
-    this.out.write(this.color(this.word));
-    this.col += w;
-    this.word = "";
-  }
-
-  /** Feed a chunk of streamed text. */
-  write(text: string) {
-    for (const ch of text) {
-      if (ch === "\r") continue; // normalize CRLF / stray CR from providers
-      if (ch === "\n") { this.flushWord(); this.newline(); continue; }
-      if (ch === " " || ch === "\t") {
-        this.flushWord();
-        if (this.col > 0 && this.col < this.maxCols) { this.startLine(); this.out.write(" "); this.col += 1; }
-        continue;
-      }
-      const cp = ch.codePointAt(0) || 0;
-      if (charWidth(cp) === 2) {
-        // CJK / wide: flush any pending latin word, then place this glyph
-        this.flushWord();
-        if (this.col > 0 && this.col + 2 > this.maxCols) this.newline();
-        this.startLine();
-        this.out.write(this.color(ch));
-        this.col += 2;
-      } else {
-        this.word += ch;
-        // very long unbroken token: hard-break to avoid overflow
-        if (visualWidth(this.word) >= this.maxCols) this.flushWord();
-      }
-    }
-  }
-
-  /** Flush any buffered word (call before switching styles / ending). */
-  flush() { this.flushWord(); }
-}
-
-/* ════════════════════════════════════════
-   Input — readline-based, robust line editing
-   ════════════════════════════════════════ */
-/** Tab-completer for slash commands. */
-function slashCompleter(line: string): [string[], string] {
-  if (!line.startsWith("/")) return [[], line];
-  const names = SLASH_COMMANDS.map(([c]) => c.trimEnd());
-  const hits = names.filter((c) => c.startsWith(line));
-  return [hits.length ? hits : names, line];
-}
-
-/** The prompt string for an agent: a small mineral seal + chevron. */
-export function promptFor(agentName: string): string {
-  const t = agentTheme(agentName);
-  return chalk.hex(t.hex)(`  ${t.symbol} ${t.kanji} `) + chalk.hex(PALETTE.inkLight)("❯ ");
-}
-
-/** Cross-turn input history (↑/↓), shared by every per-turn reader. */
-const inputHistory: string[] = [];
-
-/**
- * Read one line with the agent-themed prompt. A fresh readline interface is
- * created and closed per call — this deliberately avoids clashing with the
- * separate readline prompts used by the setup wizard and tool-approval flow
- * (two live interfaces on one stdin corrupt input). History is preserved
- * manually across turns.
- */
-export function readLine(agentName: string, out: NodeJS.WriteStream = process.stdout): Promise<string> {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: out,
-      completer: slashCompleter,
-      terminal: process.stdin.isTTY ?? false,
-      history: [...inputHistory],
-      historySize: 200,
-    } as any);
-    rl.on("SIGINT", () => { out.write("\n" + chalk.dim("  再会。\n")); rl.close(); process.exit(0); });
-    rl.question(promptFor(agentName), (answer) => {
-      const trimmed = answer.trim();
-      if (trimmed) inputHistory.unshift(trimmed);
-      rl.close();
-      resolve(trimmed);
-    });
-  });
-}
-
-/** Render the inline slash-command palette (printed, not full-screen). */
-export function renderPalette(filter: string): string {
-  const f = filter.toLowerCase();
-  const matches = SLASH_COMMANDS.filter(([c]) => c.toLowerCase().startsWith(f));
-  const list = matches.length ? matches : SLASH_COMMANDS;
-  const lines = list.slice(0, 12).map(([cmd, desc]) => {
-    const isAgent = ["/fog", "/rain", "/frost", "/snow", "/dew", "/fair"].includes(cmd.trim());
-    const name = isAgent ? chalk.hex(agentTheme(cmd.trim().slice(1)).hex)(cmd.padEnd(12)) : chalk.hex(PALETTE.inkMid)(cmd.padEnd(12));
-    return "    " + name + chalk.hex(PALETTE.inkLight)(desc);
-  });
-  return chalk.dim("  命令 · Tab 补全\n") + lines.join("\n") + "\n";
-}
+/**
+ * 天空织机 TUI — a polished *linear* terminal interface.
+ *
+ * Design note: the previous version tried to be a full-screen app, redrawing
+ * the whole screen on every keystroke while the reply streamed linearly below
+ * it — the two fought, the conversation never persisted, and hand-rolled
+ * raw-mode editing mangled CJK width. This rewrite is linear (like Claude Code
+ * / opencode): real readline line-editing + a CJK-aware wrapping stream
+ * renderer. Robust, flicker-free, and it actually reads like a conversation.
+ */
+
+import * as readline from "readline";
+import chalk from "chalk";
+import { agentTheme, PALETTE } from "../core/theme";
+
+const TUI_VERSION = (() => { try { return require("../../package.json").version; } catch { return ""; } })();
+
+export interface TUIContext {
+  agent: any;
+  agents: Map<string, any>;
+  model: string;
+  cost: string;
+  width: number;
+  height: number;
+}
+
+/* ── Slash commands (for tab-completion + the inline palette) ── */
+export const SLASH_COMMANDS: [string, string][] = [
+  ["/fog", "≋ 雾 · 探索洞察"],
+  ["/rain", "⸽ 雨 · 创造产出"],
+  ["/frost", "✱ 霜 · 精炼品质"],
+  ["/snow", "❉ 雪 · 架构规划"],
+  ["/dew", "∘ 露 · 可靠守护"],
+  ["/fair", "☼ 晴 · 情感陪伴"],
+  ["/help", "查看所有命令"],
+  ["/setup", "配置向导"],
+  ["/init", "扫描项目生成 SKY.md"],
+  ["/plan", "切换计划模式（只读出方案）"],
+  ["/verify", "运行项目验证命令"],
+  ["/context", "上下文占用明细"],
+  ["/rewind", "回退本轮文件改动"],
+  ["/tools", "工具调用统计"],
+  ["/model", "查看/切换模型（独立/统一）"],
+  ["/cost", "费用统计"],
+  ["/status", "状态总览"],
+  ["/memory", "记忆状态"],
+  ["/sessions", "会话列表"],
+  ["/resume ", "恢复会话（序号/id）"],
+  ["/new", "开始新会话"],
+  ["/workspace", "工作空间"],
+  ["/compact", "压缩上下文"],
+  ["/clear", "清屏"],
+  ["/task ", "多 Agent 编排"],
+  ["/mcp", "MCP 服务器"],
+  ["/version", "版本信息"],
+  ["/quit", "退出"],
+];
+
+/* ════════════════════════════════════════
+   CJK-aware display width
+   ════════════════════════════════════════ */
+/** Visual columns occupied by a single code point (CJK / fullwidth = 2). */
+export function charWidth(cp: number): number {
+  if (cp === 0) return 0;
+  if (cp < 32 || (cp >= 0x7f && cp < 0xa0)) return 0; // control
+  // East-Asian wide / fullwidth ranges
+  if (
+    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals, Kangxi, punctuation
+    (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana…CJK symbols
+    (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Ext A
+    (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified
+    (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK compat
+    (cp >= 0xfe10 && cp <= 0xfe19) ||
+    (cp >= 0xfe30 && cp <= 0xfe6f) || // CJK compat forms
+    (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth forms
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f300 && cp <= 0x1faff) // emoji / pictographs
+  ) return 2;
+  return 1;
+}
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/** Visual width of a string, ignoring ANSI color codes. */
+export function visualWidth(s: string): number {
+  let w = 0;
+  for (const ch of s.replace(ANSI_RE, "")) w += charWidth(ch.codePointAt(0) || 0);
+  return w;
+}
+
+/** Pad a string (containing ANSI) to a visual width. */
+export function padVisual(s: string, width: number): string {
+  const diff = width - visualWidth(s);
+  return diff > 0 ? s + " ".repeat(diff) : s;
+}
+
+/* ════════════════════════════════════════
+   Streaming renderer — word-wrap aware, CJK aware
+   ════════════════════════════════════════ */
+/**
+ * Writes streamed text with a fixed left gutter, wrapping at the terminal
+ * width. English wraps on word boundaries; CJK wraps per glyph. Color is
+ * applied per flushed chunk so styling survives wrapping.
+ */
+export class StreamRenderer {
+  private col = 0;
+  private word = "";
+  private atLineStart = true;
+  private out: NodeJS.WriteStream;
+  private gutter: string;
+  private maxCols: number;
+  private color: (s: string) => string;
+
+  constructor(out: NodeJS.WriteStream, opts?: { gutter?: string; color?: (s: string) => string }) {
+    this.out = out;
+    this.gutter = opts?.gutter ?? "  ";
+    this.color = opts?.color ?? ((s) => s);
+    const cols = out.columns || 80;
+    // content width excludes the gutter; clamp for readability
+    this.maxCols = Math.max(32, Math.min(cols - visualWidth(this.gutter) - 1, 96));
+  }
+
+  /** Lazily emit the left gutter at the start of each visual line. */
+  private startLine() { if (this.atLineStart) { this.out.write(this.gutter); this.atLineStart = false; } }
+  private newline() { this.out.write("\n"); this.atLineStart = true; this.col = 0; }
+
+  private flushWord() {
+    if (!this.word) return;
+    const w = visualWidth(this.word);
+    if (this.col > 0 && this.col + w > this.maxCols) this.newline();
+    this.startLine();
+    this.out.write(this.color(this.word));
+    this.col += w;
+    this.word = "";
+  }
+
+  /** Feed a chunk of streamed text. */
+  write(text: string) {
+    for (const ch of text) {
+      if (ch === "\r") continue; // normalize CRLF / stray CR from providers
+      if (ch === "\n") { this.flushWord(); this.newline(); continue; }
+      if (ch === " " || ch === "\t") {
+        this.flushWord();
+        if (this.col > 0 && this.col < this.maxCols) { this.startLine(); this.out.write(" "); this.col += 1; }
+        continue;
+      }
+      const cp = ch.codePointAt(0) || 0;
+      if (charWidth(cp) === 2) {
+        // CJK / wide: flush any pending latin word, then place this glyph
+        this.flushWord();
+        if (this.col > 0 && this.col + 2 > this.maxCols) this.newline();
+        this.startLine();
+        this.out.write(this.color(ch));
+        this.col += 2;
+      } else {
+        this.word += ch;
+        // very long unbroken token: hard-break to avoid overflow
+        if (visualWidth(this.word) >= this.maxCols) this.flushWord();
+      }
+    }
+  }
+
+  /** Flush any buffered word (call before switching styles / ending). */
+  flush() { this.flushWord(); }
+}
+
+/* ════════════════════════════════════════
+   Input — readline-based, robust line editing
+   ════════════════════════════════════════ */
+/** Tab-completer for slash commands. */
+function slashCompleter(line: string): [string[], string] {
+  if (!line.startsWith("/")) return [[], line];
+  const names = SLASH_COMMANDS.map(([c]) => c.trimEnd());
+  const hits = names.filter((c) => c.startsWith(line));
+  return [hits.length ? hits : names, line];
+}
+
+/** The prompt string for an agent: a small mineral seal + chevron. */
+export function promptFor(agentName: string): string {
+  const t = agentTheme(agentName);
+  return chalk.hex(t.hex)(`  ${t.symbol} ${t.kanji} `) + chalk.hex(PALETTE.inkLight)("❯ ");
+}
+
+/** Cross-turn input history (↑/↓), shared by every per-turn reader. */
+const inputHistory: string[] = [];
+
+/**
+ * Read one line with the agent-themed prompt. A fresh readline interface is
+ * created and closed per call — this deliberately avoids clashing with the
+ * separate readline prompts used by the setup wizard and tool-approval flow
+ * (two live interfaces on one stdin corrupt input). History is preserved
+ * manually across turns.
+ */
+export function readLine(agentName: string, out: NodeJS.WriteStream = process.stdout): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: out,
+      completer: slashCompleter,
+      terminal: process.stdin.isTTY ?? false,
+      history: [...inputHistory],
+      historySize: 200,
+    } as any);
+    rl.on("SIGINT", () => { out.write("\n" + chalk.dim("  再会。\n")); rl.close(); process.exit(0); });
+    rl.question(promptFor(agentName), (answer) => {
+      const trimmed = answer.trim();
+      if (trimmed) inputHistory.unshift(trimmed);
+      rl.close();
+      resolve(trimmed);
+    });
+  });
+}
+
+/** Render the inline slash-command palette (printed, not full-screen). */
+export function renderPalette(filter: string): string {
+  const f = filter.toLowerCase();
+  const matches = SLASH_COMMANDS.filter(([c]) => c.toLowerCase().startsWith(f));
+  const list = matches.length ? matches : SLASH_COMMANDS;
+  const lines = list.slice(0, 12).map(([cmd, desc]) => {
+    const isAgent = ["/fog", "/rain", "/frost", "/snow", "/dew", "/fair"].includes(cmd.trim());
+    const name = isAgent ? chalk.hex(agentTheme(cmd.trim().slice(1)).hex)(cmd.padEnd(12)) : chalk.hex(PALETTE.inkMid)(cmd.padEnd(12));
+    return "    " + name + chalk.hex(PALETTE.inkLight)(desc);
+  });
+  return chalk.dim("  命令 · Tab 补全\n") + lines.join("\n") + "\n";
+}

package/src/core/agent/guard.ts

@@ -0,0 +1,134 @@
+/**
+ * Anti-loop guard for the agent reasoning loop.
+ *
+ * Extracted from chatStreamImpl (Phase 3). Holds the per-turn heuristic state
+ * (recent response texts, tool-call signatures, tool outcomes + once-only hint
+ * flags) and, after each round, returns a decision: zero or more system
+ * "hints" to nudge the model, and optionally a hard `stop` (assistant note +
+ * a user-visible content line). The agent loop applies the decision — the guard
+ * itself has no side effects, which makes every branch unit-testable.
+ *
+ * A fresh LoopGuard is created per turn (state must not leak across turns).
+ */
+
+import type { ToolCall } from '../llm';
+import {
+  toolCallSignature,
+  textSimilarity,
+  looksLikeFailedToolResult,
+  parseToolArgs,
+  SIG_WINDOW,
+  SIG_LOOP_HINT,
+  SIG_LOOP_HARDSTOP,
+} from '../agent_helpers';
+
+/** A hard stop: record `note` as an assistant message, then surface `contentLine`. */
+export interface GuardStop {
+  note: string;
+  contentLine: string;
+}
+
+/** The guard's decision for one round. `hints` apply in order; `stop` ends the turn. */
+export interface GuardDecision {
+  hints: string[];
+  stop?: GuardStop;
+}
+
+/** Minimal shape of a tool execution result the guard inspects. */
+export interface GuardExecResult {
+  toolName: string;
+  success: boolean;
+  result: string;
+}
+
+export class LoopGuard {
+  private recentResponseTexts: string[] = [];
+  private recentToolSigs: string[] = [];
+  private recentToolOutcomes: boolean[] = [];
+  private searchCount = 0; // cumulative search/fetch calls this turn (not window-bounded)
+  private repetitionHintInjected = false;
+  private toolLoopHintInjected = false; // shared by tool-signature loop + search-storm
+  private stuckHintInjected = false;
+
+  /**
+   * Observe one completed round. Mutates internal state and returns the
+   * hints/stop decision. Evaluation order (and the shared hint flag) mirrors
+   * the original inline logic exactly.
+   */
+  observe(
+    roundContent: string,
+    toolCallsReceived: ToolCall[],
+    execResults: Array<GuardExecResult | null>
+  ): GuardDecision {
+    const hints: string[] = [];
+
+    // 1. Narration-loop: response too similar to a recent one.
+    const normalizedRound = (roundContent || '').trim();
+    if (normalizedRound && this.recentResponseTexts.length > 0) {
+      const highSim = this.recentResponseTexts.slice(-2).some(prev => textSimilarity(normalizedRound, prev) >= 0.7);
+      if (highSim && !this.repetitionHintInjected) {
+        hints.push('[Stop narrating] Your last response is highly similar to your previous one. Stop writing prose. Either: (1) emit ONLY the next tool call, or (2) output the final deliverable.');
+        this.repetitionHintInjected = true;
+      }
+    }
+    this.recentResponseTexts.push(normalizedRound);
+    if (this.recentResponseTexts.length > 3) this.recentResponseTexts.shift();
+
+    // 2. Tool-signature loop: same call repeated within the window.
+    for (const tc of toolCallsReceived) {
+      const tName = tc.function.name;
+      if (['task_done', 'list_skills', 'use_skill'].includes(tName)) continue;
+      if (['web_search', 'fetch_page', 'http_get'].includes(tName)) this.searchCount++;
+      const rawArgs = tc.function.arguments;
+      const tArgs = typeof rawArgs === 'string' ? parseToolArgs(rawArgs) : rawArgs;
+      const sig = toolCallSignature(tName, tArgs);
+      if (sig) this.recentToolSigs.push(sig);
+    }
+    if (this.recentToolSigs.length > SIG_WINDOW) {
+      this.recentToolSigs.splice(0, this.recentToolSigs.length - SIG_WINDOW);
+    }
+    if (this.recentToolSigs.length > 0) {
+      const counts = new Map<string, number>();
+      for (const s of this.recentToolSigs) counts.set(s, (counts.get(s) || 0) + 1);
+      let topSig = '';
+      let topCount = 0;
+      for (const [s, c] of counts) { if (c > topCount) { topSig = s; topCount = c; } }
+      if (topCount >= SIG_LOOP_HINT && !this.toolLoopHintInjected) {
+        hints.push(`[Tool loop] You have called \`${topSig}\` ${topCount}x in the last ${this.recentToolSigs.length} tool calls — you are iterating without converging. STOP repeating it.`);
+        this.toolLoopHintInjected = true;
+      }
+      if (topCount >= SIG_LOOP_HARDSTOP) {
+        return { hints, stop: { note: `I have repeated \`${topSig}\` ${topCount} times without converging. Stopping.`, contentLine: `\n\n[stuck] tool \`${topSig}\` repeated ${topCount}x — stopping.` } };
+      }
+    }
+
+    // 3. Stuck-loop: most/all recent tool calls failed.
+    for (const r of execResults) {
+      if (!r || r.toolName === 'task_done') continue;
+      const failed = !r.success || (typeof r.result === 'string' && looksLikeFailedToolResult(r.result));
+      this.recentToolOutcomes.push(!failed);
+      // Keep 8 so the "all recent calls failed" (>=8) hard-stop below is reachable.
+      if (this.recentToolOutcomes.length > 8) this.recentToolOutcomes.shift();
+    }
+    if (!this.stuckHintInjected && this.recentToolOutcomes.length >= 5 &&
+        this.recentToolOutcomes.filter(Boolean).length <= 1) {
+      hints.push('[Recovery hint] Your last several tool calls have mostly failed. Synthesize a partial answer from what worked or ask the user for guidance.');
+      this.stuckHintInjected = true;
+    }
+    if (this.recentToolOutcomes.length >= 8 && this.recentToolOutcomes.every(x => !x)) {
+      return { hints, stop: { note: 'Every recent tool call failed. Please give me more context.', contentLine: '\n\n[stuck] every recent tool call failed — stopping.\n' } };
+    }
+
+    // 4. Search-storm: cumulative search/fetch calls this turn (not bounded by
+    // SIG_WINDOW, so the >=12 hard-stop is actually reachable).
+    if (this.searchCount >= 8 && !this.toolLoopHintInjected) {
+      hints.push(`[Search storm] ${this.searchCount} search calls. STOP searching and synthesize.`);
+      this.toolLoopHintInjected = true;
+    }
+    if (this.searchCount >= 12) {
+      return { hints, stop: { note: 'Too many search requests. Synthesizing best answer.', contentLine: `\n\n[stuck] excessive web searching (${this.searchCount} calls) — stopping.\n` } };
+    }
+
+    return { hints };
+  }
+}