@pify/swarm 0.7.6 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @pify/swarm
 
-[![npm version](https://img.shields.io/npm/v/@pify/swarm)](https://www.npmjs.com/package/@pify/swarm) [![npm downloads](https://img.shields.io/npm/dm/@pify/swarm)](https://www.npmjs.com/package/@pify/swarm)
+[![CI](https://github.com/pifydev/swarm/actions/workflows/ci.yml/badge.svg)](https://github.com/pifydev/swarm/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@pify/swarm)](https://www.npmjs.com/package/@pify/swarm) [![npm downloads](https://img.shields.io/npm/dm/@pify/swarm)](https://www.npmjs.com/package/@pify/swarm)
 
 Run many [pi](https://github.com/earendil-works/pi) agents in parallel. One tool call fans a list of independent items out to child agents — with per-item routing, a concurrency queue, a live widget, and one aggregated report.
 

package/extensions/swarm.ts

@@ -26,6 +26,7 @@ import { Type } from "typebox";
 
 import { BUILTIN_AGENTS } from "../src/builtin.ts";
 import { withUiLock } from "../src/ui-lock.ts";
+import { LoopGuard } from "../src/loop-guard.ts";
 import {
   consentQuestion,
   decideConsent,
@@ -183,6 +184,7 @@ export default function swarm(pi: ExtensionAPI) {
     let session: AgentSession | null = null;
     let unsubscribe: (() => void) | null = null;
     let releaseLive: (() => void) | null = null;
+    let stallReason: string | null = null;
     try {
       let model = ctx.model ?? null;
       if (def.model) {
@@ -230,11 +232,37 @@ export default function swarm(pi: ExtensionAPI) {
       session = created.session;
       releaseLive = live.register(runId, session);
 
+      const guard = new LoopGuard();
       unsubscribe = session.subscribe((event) => {
-        if (event.type === "message_end" && (event as { message?: { role?: string } }).message?.role === "assistant") {
+        const message = (
+          event as {
+            message?: {
+              role?: string;
+              usage?: { totalTokens?: number };
+              content?: Array<{ type?: string; text?: string }>;
+            };
+          }
+        ).message;
+        if (event.type === "message_end" && message?.role === "assistant") {
           item.turns++;
-          const usage = (event as { message?: { usage?: { totalTokens?: number } } }).message?.usage;
+          const usage = message.usage;
           if (usage && typeof usage.totalTokens === "number") item.tokens += usage.totalTokens;
+
+          // Stop an item that is spinning — restating itself without acting —
+          // rather than letting it run to the turn cap. See loop-guard.ts.
+          if (!stallReason && Array.isArray(message.content)) {
+            const usedTool = message.content.some((c) => c.type === "toolCall");
+            const turnText = message.content
+              .filter((c) => c.type === "text" && typeof c.text === "string")
+              .map((c) => c.text)
+              .join("\n");
+            const verdict = guard.observe({ text: turnText, usedTool });
+            if (verdict.stalled) {
+              stallReason = verdict.reason ?? "no progress";
+              void session?.abort().catch(() => {});
+            }
+          }
+
           renderWidget();
           if (item.turns >= def.maxTurns) void session?.abort().catch(() => {});
         }
@@ -255,9 +283,18 @@ export default function swarm(pi: ExtensionAPI) {
         .join("\n")
         .trim();
 
-      item.result = text || null;
-      item.status =
-        last?.stopReason === "aborted" ? "aborted" : last?.stopReason === "error" ? "error" : "done";
+      // An item the loop guard stopped gave up rather than concluded — mark it
+      // so the aggregated report does not read it as a finished answer.
+      item.result = stallReason
+        ? `${text ? `${text}\n\n` : ""}[stopped: no progress — the agent ${stallReason}]`
+        : text || null;
+      item.status = stallReason
+        ? "aborted"
+        : last?.stopReason === "aborted"
+          ? "aborted"
+          : last?.stopReason === "error"
+            ? "error"
+            : "done";
       if (item.status === "error") item.error = text || "child session error";
       // A child that stopped cleanly and said nothing has not answered — the
       // fix subagent already carries and this executor never received. Left

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/swarm",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "Coordinate multiple pi agents in parallel: swarm_run fan-out with per-item auto-routing, concurrency queue, aggregated reports",
   "keywords": [
     "pi-package",

package/src/loop-guard.ts

@@ -0,0 +1,90 @@
+/**
+ * Stop a child that has stopped making progress.
+ *
+ * A turn cap bounds what a runaway child can cost; it does not notice the
+ * characteristic autonomous-agent failure, which is cheaper per turn and just
+ * as stuck: restating the same plan every turn without calling a tool, or
+ * oscillating between two states forever. pi's own loop will happily let that
+ * run to the cap.
+ *
+ * So fingerprint each assistant turn and watch for two shapes. A turn that
+ * called a tool is progress and clears the history — the guard only fires on
+ * turns that did nothing but talk. `repeat` identical tool-free turns is a
+ * child spinning in place; an A-B-A-B… run of `cycle` cycles is one bouncing
+ * between two dead ends. Both are advisory signals the caller acts on (a
+ * spawned child is unattended, so acting means aborting it).
+ *
+ * Zero dependencies — node:crypto for the hash. Deterministic and pure given
+ * the sequence of turns, so it is unit-testable without a live child.
+ */
+import { createHash } from "node:crypto";
+
+export interface LoopGuardConfig {
+  /** Consecutive identical tool-free turns before flagging a stall (min 2, default 3). */
+  repeat?: number;
+  /** Repeats of a two-turn A-B cycle before flagging (min 2, default 3). */
+  cycle?: number;
+}
+
+export interface Turn {
+  /** The visible assistant text of the turn. */
+  text: string;
+  /** Did the turn invoke at least one tool? A tool call is progress. */
+  usedTool: boolean;
+}
+
+export interface LoopVerdict {
+  stalled: boolean;
+  reason?: string;
+}
+
+/** Fold away cosmetic differences so "the same thought" hashes the same. */
+function fingerprint(text: string): string {
+  const norm = text.normalize("NFKC").toLowerCase().replace(/\s+/g, " ").trim();
+  return createHash("sha256").update(norm).digest("hex");
+}
+
+export class LoopGuard {
+  private readonly repeat: number;
+  private readonly cycle: number;
+  /** Recent tool-free fingerprints; a tool call clears this. */
+  private readonly recent: string[] = [];
+  private static readonly MAX = 16;
+
+  constructor(cfg: LoopGuardConfig = {}) {
+    this.repeat = Math.max(2, cfg.repeat ?? 3);
+    this.cycle = Math.max(2, cfg.cycle ?? 3);
+  }
+
+  observe(turn: Turn): LoopVerdict {
+    // A tool call is forward motion: forget the stall history entirely.
+    if (turn.usedTool) {
+      this.recent.length = 0;
+      return { stalled: false };
+    }
+    // A silent turn (no text, no tool) is not evidence of a loop by itself.
+    if (turn.text.trim() === "") return { stalled: false };
+
+    const fp = fingerprint(turn.text);
+    this.recent.push(fp);
+    if (this.recent.length > LoopGuard.MAX) this.recent.shift();
+
+    // Spinning in place: the last `repeat` tool-free turns are identical.
+    if (this.recent.length >= this.repeat && this.recent.slice(-this.repeat).every((f) => f === fp)) {
+      return { stalled: true, reason: `repeated the same output for ${this.repeat} turns without acting` };
+    }
+
+    // Oscillating: the last 2×cycle turns are a strict A-B-A-B… alternation.
+    const need = 2 * this.cycle;
+    if (this.recent.length >= need) {
+      const tail = this.recent.slice(-need);
+      const a = tail[0]!;
+      const b = tail[1]!;
+      if (a !== b && tail.every((f, i) => f === (i % 2 === 0 ? a : b))) {
+        return { stalled: true, reason: `oscillated between two states for ${this.cycle} cycles without acting` };
+      }
+    }
+
+    return { stalled: false };
+  }
+}