skyloom 1.13.4 → 1.13.6

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "skyloom",
-  "version": "1.13.4",
-  "description": "天空织机 Skyloom — 6 weather-themed AI agents: Fog, Rain, Frost, Snow, Dew, Fair",
-  "preferGlobal": true,
-  "type": "commonjs",
-  "main": "./dist/index.js",
-  "bin": {
-    "sky": "dist/cli/main.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node ./dist/cli/main.js",
-    "chat": "node ./dist/cli/main.js chat",
-    "task": "node ./dist/cli/main.js task",
-    "web": "node ./dist/cli/main.js web",
-    "test": "vitest",
-    "test:coverage": "vitest --coverage",
-    "lint": "eslint src --ext .ts",
-    "type-check": "tsc --noEmit",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "pretest": "npm run type-check",
-    "setup": "node scripts/install.js",
-    "postinstall": "node scripts/link.js"
-  },
-  "keywords": [
-    "multi-agent",
-    "llm",
-    "orchestration",
-    "ai",
-    "tool-use"
-  ],
-  "author": "Skyloom Team",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/susurrune/skyloom-ts.git"
-  },
-  "homepage": "https://github.com/susurrune/skyloom-ts#readme",
-  "bugs": {
-    "url": "https://github.com/susurrune/skyloom-ts/issues"
-  },
-  "dependencies": {
-    "axios": "^1.7.7",
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "glob": "^11.0.0",
-    "sql.js": "^1.14.1",
-    "yaml": "^2.4.1"
-  },
-  "devDependencies": {
-    "@types/glob": "^8.1.0",
-    "@types/node": "^22.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "@vitest/coverage-v8": "^2.0.0",
-    "@vitest/ui": "^2.0.0",
-    "eslint": "^9.0.0",
-    "prettier": "^3.2.0",
-    "tsx": "^4.7.0",
-    "typescript": "^5.4.0",
-    "vitest": "^2.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "skyloom",
+  "version": "1.13.6",
+  "description": "天空织机 Skyloom — 6 weather-themed AI agents: Fog, Rain, Frost, Snow, Dew, Fair",
+  "preferGlobal": true,
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "bin": {
+    "sky": "dist/cli/main.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node ./dist/cli/main.js",
+    "chat": "node ./dist/cli/main.js chat",
+    "task": "node ./dist/cli/main.js task",
+    "web": "node ./dist/cli/main.js web",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --ext .ts",
+    "type-check": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "pretest": "npm run type-check",
+    "setup": "node scripts/install.js",
+    "postinstall": "node scripts/link.js"
+  },
+  "keywords": [
+    "multi-agent",
+    "llm",
+    "orchestration",
+    "ai",
+    "tool-use"
+  ],
+  "author": "Skyloom Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/susurrune/skyloom-ts.git"
+  },
+  "homepage": "https://github.com/susurrune/skyloom-ts#readme",
+  "bugs": {
+    "url": "https://github.com/susurrune/skyloom-ts/issues"
+  },
+  "dependencies": {
+    "axios": "^1.7.7",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "glob": "^11.0.0",
+    "sql.js": "^1.14.1",
+    "yaml": "^2.4.1"
+  },
+  "devDependencies": {
+    "@types/glob": "^8.1.0",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "@vitest/ui": "^2.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.2.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli/main.ts

@@ -153,8 +153,19 @@ async function streamResponse(agent: any, input: string): Promise<void> {
   const header = () => { if (!headerShown) { out.write("\n  " + chalk.bold.hex(theme.hex)(`${theme.symbol} ${theme.kanji}`) + chalk.hex(theme.hex)(` ${theme.name}`) + "\n\n"); headerShown = true; } };
   const endBlock = () => { if (renderer) { renderer.flush(); renderer = null; out.write("\n"); } };
 
+  // ── Ctrl-C interrupts this turn (keeps partial output); a 2nd Ctrl-C exits. ──
+  const controller = new AbortController();
+  let interrupted = false;
+  const onSigint = () => {
+    if (interrupted) { out.write(chalk.dim("\n  再会。\n")); process.exit(130); }
+    interrupted = true;
+    controller.abort();
+  };
+  process.on("SIGINT", onSigint);
+
   try {
-    for await (const ev of agent.chatStream(input)) {
+    for await (const ev of agent.chatStream(input, controller.signal)) {
+      if (ev.type === "interrupted") { interrupted = true; continue; }
       switch (ev.type) {
         case "reasoning":
           stopSpinner();
@@ -185,10 +196,15 @@ async function streamResponse(agent: any, input: string): Promise<void> {
           break;
       }
     }
+  } catch (e: any) {
+    // Abort surfaces here only if the network rejected before a clean stop.
+    if (!interrupted && e?.name !== "AbortError") throw e;
   } finally {
+    process.removeListener("SIGINT", onSigint);
     stopSpinner();
     endBlock();
   }
+  if (interrupted) out.write(chalk.dim("\n  ⊘ 已中断（保留以上内容）\n"));
   out.write("\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 };
+  }
+}

package/src/core/agent.ts

@@ -14,22 +14,17 @@ import { Skill, SkillRegistry } from './skill';
 import { type ToolDefinition, ToolRegistry } from './tool';
 import {
   parseToolArgs,
-  looksLikeFailedToolResult,
   extractFilePathsFromMessages,
   enrichResponseWithArtifacts,
-  toolCallSignature,
-  textSimilarity,
   formatArgsParseError,
   suggestToolNames,
   toolStatusLabel,
   synthesizeDelegationSummary,
   parseExtractedFacts,
-  SIG_WINDOW,
-  SIG_LOOP_HINT,
-  SIG_LOOP_HARDSTOP,
 } from './agent_helpers';
 import { selectRelevantTools } from './tool_router';
 import { getModelInfo } from './catalog';
+import { LoopGuard } from './agent/guard';
 
 const log = getLogger('agent');
 
@@ -708,12 +703,12 @@ export class BaseAgent {
     }
   }
 
-  async *chatStream(message: string): AsyncGenerator<Record<string, any>> {
+  async *chatStream(message: string, signal?: AbortSignal): AsyncGenerator<Record<string, any>> {
     const activatedNow = this.autoActivateSkills(message);
     const self = this;
 
     try {
-      for await (const ev of self.chatStreamImpl(message, activatedNow.length > 0 ? activatedNow : undefined)) {
+      for await (const ev of self.chatStreamImpl(message, activatedNow.length > 0 ? activatedNow : undefined, signal)) {
         yield ev;
       }
     } catch (err) {
@@ -727,7 +722,8 @@ export class BaseAgent {
 
   protected async *chatStreamImpl(
     message: string,
-    autoActivated?: string[]
+    autoActivated?: string[],
+    signal?: AbortSignal
   ): AsyncGenerator<Record<string, any>> {
     await this.setState(AgentState.THINKING);
     this.memory.addMessage('user', message);
@@ -748,12 +744,7 @@ export class BaseAgent {
       );
     }
 
-    const recentToolOutcomes: boolean[] = [];
-    let stuckHintInjected = false;
-    const recentResponseTexts: string[] = [];
-    let repetitionHintInjected = false;
-    const recentToolSigs: string[] = [];
-    let toolLoopHintInjected = false;
+    const guard = new LoopGuard();
 
     let toolNamesCache: string[] | null = null;
     let cacheKey: string | null = null;
@@ -779,6 +770,19 @@ export class BaseAgent {
       let roundCount = 0;
 
       while (true) {
+        // User interrupt between rounds (Ctrl-C): stop before another LLM call.
+        if (signal?.aborted) {
+          if (!assistantStored && fullContent.trim()) {
+            this.memory.addMessage('assistant', fullContent);
+            assistantStored = true;
+          } else if (!assistantStored) {
+            this.popLastUserMessage();
+          }
+          await this.setState(AgentState.IDLE);
+          yield { type: 'interrupted' };
+          yield { type: 'done' };
+          return;
+        }
         if (roundCount >= roundLimit) {
           if (roundLimit >= this._maxToolRoundsHardCap) break;
           const extendBy = Math.min(15, this._maxToolRoundsHardCap - roundLimit);
@@ -802,7 +806,8 @@ export class BaseAgent {
           this.name,
           toolNames.length > 0 ? toolNames : undefined,
           toolNames.length > 0 ? this.toolRegistry : undefined,
-          Object.keys(this.getSkillConfigOverrides()).length > 0 ? this.getSkillConfigOverrides() : undefined
+          Object.keys(this.getSkillConfigOverrides()).length > 0 ? this.getSkillConfigOverrides() : undefined,
+          signal
         )) {
           if (event.type === 'content') {
             fullContent += event.text;
@@ -899,82 +904,12 @@ export class BaseAgent {
           return;
         }
 
-        // ── Narration-loop detection ──
-        const normalizedRound = roundContent.trim();
-        if (normalizedRound && recentResponseTexts.length > 0) {
-          const highSim = recentResponseTexts.slice(-2).some(prev => textSimilarity(normalizedRound, prev) >= 0.7);
-          if (highSim && !repetitionHintInjected) {
-            this.memory.addMessage('system', '[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.');
-            repetitionHintInjected = true;
-          }
-        }
-        recentResponseTexts.push(normalizedRound);
-        if (recentResponseTexts.length > 3) recentResponseTexts.shift();
-
-        // ── Tool-signature loop detection ──
-        for (const tc of toolCallsReceived) {
-          const tName = tc.function.name;
-          if (['task_done', 'list_skills', 'use_skill'].includes(tName)) continue;
-          const rawArgs = tc.function.arguments;
-          const tArgs = typeof rawArgs === 'string' ? parseToolArgs(rawArgs) : rawArgs;
-          const sig = toolCallSignature(tName, tArgs);
-          if (sig) recentToolSigs.push(sig);
-        }
-        if (recentToolSigs.length > SIG_WINDOW) {
-          recentToolSigs.splice(0, recentToolSigs.length - SIG_WINDOW);
-        }
-        if (recentToolSigs.length > 0) {
-          const counts = new Map<string, number>();
-          for (const s of 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 && !toolLoopHintInjected) {
-            this.memory.addMessage('system', `[Tool loop] You have called \`${topSig}\` ${topCount}x in the last ${recentToolSigs.length} tool calls — you are iterating without converging. STOP repeating it.`);
-            toolLoopHintInjected = true;
-          }
-          if (topCount >= SIG_LOOP_HARDSTOP) {
-            this.memory.addMessage('assistant', `I have repeated \`${topSig}\` ${topCount} times without converging. Stopping.`);
-            yield { type: 'content', text: `\n\n[stuck] tool \`${topSig}\` repeated ${topCount}x — stopping.` };
-            await this.setState(AgentState.IDLE);
-            yield { type: 'done' };
-            return;
-          }
-        }
-
-        // ── Stuck-loop detection ──
-        for (const r of execResults) {
-          if (!r || r.toolName === 'task_done') continue;
-          const failed = !r.success || (typeof r.result === 'string' && looksLikeFailedToolResult(r.result));
-          recentToolOutcomes.push(!failed);
-          if (recentToolOutcomes.length > 6) recentToolOutcomes.shift();
-        }
-
-        if (!stuckHintInjected && recentToolOutcomes.length >= 5 &&
-            recentToolOutcomes.filter(Boolean).length <= 1) {
-          this.memory.addMessage('system', '[Recovery hint] Your last several tool calls have mostly failed. Synthesize a partial answer from what worked or ask the user for guidance.');
-          stuckHintInjected = true;
-        }
-
-        if (recentToolOutcomes.length >= 8 && recentToolOutcomes.every(x => !x)) {
-          this.memory.addMessage('assistant', 'Every recent tool call failed. Please give me more context.');
-          yield { type: 'content', text: '\n\n[stuck] every recent tool call failed — stopping.\n' };
-          await this.setState(AgentState.IDLE);
-          yield { type: 'done' };
-          return;
-        }
-
-        // ── Search-storm detection ──
-        const searchStormCount = recentToolSigs.filter(s =>
-          s.startsWith('web_search:') || ['fetch_page', 'http_get'].includes(s)
-        ).length;
-        if (searchStormCount >= 8 && !toolLoopHintInjected) {
-          this.memory.addMessage('system', `[Search storm] ${searchStormCount} search calls. STOP searching and synthesize.`);
-          toolLoopHintInjected = true;
-        }
-        if (searchStormCount >= 12) {
-          this.memory.addMessage('assistant', 'Too many search requests. Synthesizing best answer.');
-          yield { type: 'content', text: `\n\n[stuck] excessive web searching (${searchStormCount} calls) — stopping.\n` };
+        // ── Anti-loop guard (narration / tool-signature / stuck / search-storm) ──
+        const decision = guard.observe(roundContent, toolCallsReceived, execResults);
+        for (const hint of decision.hints) this.memory.addMessage('system', hint);
+        if (decision.stop) {
+          this.memory.addMessage('assistant', decision.stop.note);
+          yield { type: 'content', text: decision.stop.contentLine };
           await this.setState(AgentState.IDLE);
           yield { type: 'done' };
           return;

package/src/core/llm.ts

@@ -802,7 +802,7 @@ export class LLMClient {
    * emitted once complete. Usage comes from the final `stream_options` chunk.
    */
   private async *callOpenAIStream(
-    m: string, messages: Record<string, unknown>[], tools?: string[], temp?: number, maxTok?: number
+    m: string, messages: Record<string, unknown>[], tools?: string[], temp?: number, maxTok?: number, signal?: AbortSignal
   ): AsyncGenerator<StreamEvent> {
     const apiKey = this.getApiKey(m);
     const baseUrl = this.getBaseUrl(m);
@@ -814,7 +814,7 @@ export class LLMClient {
       const defs = tools.map(t => this._toolRegistry.get(t)).filter(Boolean) as any[];
       if (defs.length) body.tools = defs.map(t => ({ type: "function", function: { name: t.name, description: t.description, parameters: this.paramsToSchema(t.parameters || []) } }));
     }
-    const resp = await fetch(baseUrl + "/chat/completions", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + apiKey }, body: JSON.stringify(body) });
+    const resp = await fetch(baseUrl + "/chat/completions", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + apiKey }, body: JSON.stringify(body), signal });
     if (!resp.ok || !resp.body) { const e: any = new Error("API " + resp.status + ": " + ((await resp.text()).slice(0, 200))); e.status_code = resp.status; throw e; }
 
     const reader = (resp.body as any).getReader();
@@ -861,7 +861,7 @@ export class LLMClient {
 
   async *streamWithTools(
     messages: Record<string, unknown>[], agentName?: string, tools?: string[],
-    _toolRegistry?: ToolRegistry, overrides?: Record<string, unknown>
+    _toolRegistry?: ToolRegistry, overrides?: Record<string, unknown>, signal?: AbortSignal
   ): AsyncGenerator<StreamEvent> {
     this.checkBudget();
     const ov = overrides || {};
@@ -884,12 +884,14 @@ export class LLMClient {
     let started = false;
     let usage: UsageStats = { promptTokens: 0, completionTokens: 0 };
     try {
-      for await (const ev of this.callOpenAIStream(model, messages, tools, temperature, maxTokens)) {
+      for await (const ev of this.callOpenAIStream(model, messages, tools, temperature, maxTokens, signal)) {
         if (ev.type === "content" || ev.type === "tool_call") started = true;
         if (ev.type === "done" && ev.usage) usage = ev.usage;
         yield ev;
       }
     } catch (e: any) {
+      // User interrupt (Ctrl-C): stop cleanly — keep whatever streamed, no error, no fallback.
+      if (signal?.aborted || e?.name === "AbortError") { yield { type: "done", usage }; return; }
       if (started) { yield { type: "error", text: String(e?.message || e) }; yield { type: "done", usage }; return; }
       this.log?.warn("stream_failed_fallback", { model, error: String(e?.message || e) });
       yield* blockingFallback();

package/tests/agent.test.ts

@@ -132,3 +132,28 @@ describe("agent · context window (catalog-aware compaction)", () => {
     expect((agent as any).shouldAutoCompact()).toBe(false);
   });
 });
+
+describe("agent · interrupt (Ctrl-C)", () => {
+  it("stops between rounds on abort and preserves partial output", async () => {
+    const controller = new AbortController();
+    // Round 1 streams some content + a tool call; the tool aborts the signal.
+    // Round 2 must never run.
+    const turns: Turn[] = [
+      { content: "部分内容已生成…", toolCalls: [{ name: "spin", args: {} }] },
+      { content: "不应出现的第二轮" },
+    ];
+    const reg = new ToolRegistry();
+    reg.register({ name: "spin", description: "spin", handler: async () => { controller.abort(); return "spun"; } });
+    const config = { agents: { fog: {} }, llm: {}, memory: { shortTermLimit: 200, dbPath: "/tmp/sky-test" } };
+    const agent = new FogAgent(config as any, new MockLLM(turns) as any, new MessageBus(), reg, new SkillRegistry());
+
+    const evs = await collect(agent.chatStream("go", controller.signal));
+    const text = evs.filter((e) => e.type === "content").map((e) => e.text).join("");
+
+    expect(evs.some((e) => e.type === "interrupted")).toBe(true);
+    expect(text).toContain("部分内容已生成");      // partial output kept
+    expect(text).not.toContain("第二轮");          // round 2 never streamed
+    // partial assistant content is in memory
+    expect(agent.memory.getMessages().some((m) => m.role === "assistant" && String(m.content).includes("部分内容"))).toBe(true);
+  });
+});

package/tests/guard.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+import { LoopGuard } from "../src/core/agent/guard";
+
+function toolCall(name: string, args: any = {}) {
+  return { id: "c" + Math.random(), type: "function", function: { name, arguments: JSON.stringify(args) } } as any;
+}
+const ok = (name: string) => ({ toolName: name, success: true, result: "ok" });
+const fail = (name: string) => ({ toolName: name, success: false, result: "Error: boom" });
+
+describe("LoopGuard", () => {
+  it("no hints / no stop for a normal round", () => {
+    const g = new LoopGuard();
+    const d = g.observe("hello", [toolCall("read", { path: "a" })], [ok("read")]);
+    expect(d.hints).toEqual([]);
+    expect(d.stop).toBeUndefined();
+  });
+
+  it("hard-stops when the same tool signature repeats past the threshold", () => {
+    const g = new LoopGuard();
+    let last: any;
+    for (let i = 0; i < 12; i++) last = g.observe("", [toolCall("spin", { n: 1 })], [ok("spin")]);
+    expect(last.stop).toBeDefined();
+    expect(last.stop.contentLine).toContain("repeated");
+    expect(last.stop.note).toContain("Stopping");
+  });
+
+  it("injects a tool-loop hint once before hard-stopping", () => {
+    const g = new LoopGuard();
+    const hintRounds: string[][] = [];
+    for (let i = 0; i < 12; i++) hintRounds.push(g.observe("", [toolCall("spin", { n: 1 })], [ok("spin")]).hints);
+    const allHints = hintRounds.flat();
+    expect(allHints.filter((h) => h.includes("[Tool loop]")).length).toBe(1); // once only
+  });
+
+  it("flags a narration loop when responses are near-identical", () => {
+    const g = new LoopGuard();
+    const text = "我正在分析这个问题并准备给出答案，请稍候。";
+    g.observe(text, [], []);
+    const d = g.observe(text, [], []); // same content again
+    expect(d.hints.some((h) => h.includes("Stop narrating"))).toBe(true);
+  });
+
+  it("injects a recovery hint when most recent tool calls failed", () => {
+    const g = new LoopGuard();
+    const hints: string[] = [];
+    for (let i = 0; i < 5; i++) hints.push(...g.observe("", [toolCall("t" + i)], [fail("t" + i)]).hints);
+    expect(hints.some((h) => h.includes("[Recovery hint]"))).toBe(true);
+  });
+
+  it("hard-stops when the last 8 tool calls all failed", () => {
+    const g = new LoopGuard();
+    let last: any;
+    // distinct tool names so the signature-loop guard doesn't fire first
+    for (let i = 0; i < 8; i++) last = g.observe("", [toolCall("t" + i, { i })], [fail("t" + i)]);
+    expect(last.stop).toBeDefined();
+    expect(last.stop.contentLine).toContain("every recent tool call failed");
+  });
+
+  it("hard-stops on a search storm (>=12 distinct search calls)", () => {
+    const g = new LoopGuard();
+    let last: any;
+    // cycle distinct search tools so the signature-loop guard doesn't fire first
+    const tools = ["web_search", "fetch_page", "http_get"];
+    for (let i = 0; i < 12; i++) last = g.observe("", [toolCall(tools[i % 3], { q: "x" + i })], [ok(tools[i % 3])]);
+    expect(last.stop).toBeDefined();
+    expect(last.stop.contentLine).toContain("excessive web searching");
+  });
+
+  it("ignores task_done in signature counting (never hard-stops on it)", () => {
+    const g = new LoopGuard();
+    let last: any;
+    for (let i = 0; i < 15; i++) last = g.observe("", [toolCall("task_done", {})], [ok("task_done")]);
+    expect(last.stop).toBeUndefined();
+  });
+});