@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/hooks/tool-loop-detection.test.ts

@@ -0,0 +1,158 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { checkToolLoop, clearToolHistory } from "./tool-loop-detection";
+
+const SESSION_KEY = "test-session-loop-detection";
+
+beforeEach(async () => {
+  await clearToolHistory(SESSION_KEY);
+});
+
+afterEach(async () => {
+  await clearToolHistory(SESSION_KEY);
+});
+
+describe("tool-loop-detection", () => {
+  describe("checkToolLoop — no loop", () => {
+    test("returns not blocked for first call", async () => {
+      const result = await checkToolLoop(SESSION_KEY, "Read", { file_path: "/foo.ts" });
+      expect(result.blocked).toBe(false);
+      expect(result.severity).toBeUndefined();
+    });
+
+    test("returns not blocked for varied tool calls", async () => {
+      // Simulate 10 different tool calls — should never trigger
+      for (let i = 0; i < 10; i++) {
+        const result = await checkToolLoop(SESSION_KEY, "Read", {
+          file_path: `/file-${i}.ts`,
+        });
+        expect(result.blocked).toBe(false);
+      }
+    });
+
+    test("returns not blocked below warning threshold", async () => {
+      // 7 identical calls (threshold is 8)
+      for (let i = 0; i < 7; i++) {
+        const result = await checkToolLoop(SESSION_KEY, "Bash", { command: "ls" });
+        expect(result.blocked).toBe(false);
+      }
+    });
+  });
+
+  describe("checkToolLoop — same-tool repeat detection", () => {
+    test("returns warning at 8 identical calls", async () => {
+      let result: Awaited<ReturnType<typeof checkToolLoop>> | undefined;
+      for (let i = 0; i < 8; i++) {
+        result = await checkToolLoop(SESSION_KEY, "Read", { file_path: "/same.ts" });
+      }
+      expect(result!.blocked).toBe(false);
+      expect(result!.severity).toBe("warning");
+      expect(result!.reason).toContain("8 times");
+      expect(result!.reason).toContain("Read");
+    });
+
+    test("returns critical/blocked at 15 identical calls", async () => {
+      let result: Awaited<ReturnType<typeof checkToolLoop>> | undefined;
+      for (let i = 0; i < 15; i++) {
+        result = await checkToolLoop(SESSION_KEY, "Grep", { pattern: "foo", path: "/bar" });
+      }
+      expect(result!.blocked).toBe(true);
+      expect(result!.severity).toBe("critical");
+      expect(result!.reason).toContain("15 times");
+      expect(result!.reason).toContain("Grep");
+      expect(result!.reason).toContain("stuck in a loop");
+    });
+
+    test("does not trigger for different args on same tool", async () => {
+      for (let i = 0; i < 20; i++) {
+        const result = await checkToolLoop(SESSION_KEY, "Read", {
+          file_path: `/unique-${i}.ts`,
+        });
+        expect(result.blocked).toBe(false);
+        // Should not have "critical" severity for unique calls
+        if (result.severity === "critical") {
+          throw new Error(`Unexpected critical at iteration ${i}`);
+        }
+      }
+    });
+  });
+
+  describe("checkToolLoop — ping-pong detection", () => {
+    test("detects alternating two-tool pattern at critical threshold", async () => {
+      let result: Awaited<ReturnType<typeof checkToolLoop>> | undefined;
+      // Alternate between two patterns for 12+ calls
+      for (let i = 0; i < 14; i++) {
+        if (i % 2 === 0) {
+          result = await checkToolLoop(SESSION_KEY, "Read", { file_path: "/a.ts" });
+        } else {
+          result = await checkToolLoop(SESSION_KEY, "Edit", {
+            file_path: "/a.ts",
+            old_string: "x",
+            new_string: "y",
+          });
+        }
+      }
+      // At 14 calls alternating between 2 patterns (7+7=14 >= 12 critical threshold)
+      // and dominance is 100% (14/14 >= 80%)
+      expect(result!.blocked).toBe(true);
+      expect(result!.severity).toBe("critical");
+      expect(result!.reason).toContain("ping-pong");
+    });
+
+    test("warns on ping-pong at warning threshold", async () => {
+      let result: Awaited<ReturnType<typeof checkToolLoop>> | undefined;
+      // Do 6 alternating calls (3+3=6 >= PINGPONG_WARNING_THRESHOLD)
+      // But we need enough history for the check to trigger (>= 6 history length)
+      for (let i = 0; i < 8; i++) {
+        if (i % 2 === 0) {
+          result = await checkToolLoop(SESSION_KEY, "Bash", { command: "npm test" });
+        } else {
+          result = await checkToolLoop(SESSION_KEY, "Read", { file_path: "/test.ts" });
+        }
+      }
+      // With 8 calls (4+4), dominance is 8/8=100% >= 80%, and 8 >= 6 warning threshold
+      // Should be at least warning (might be critical at 8 since >= 6 warning)
+      expect(result!.severity).toBeDefined();
+      expect(["warning", "critical"]).toContain(result!.severity!);
+    });
+  });
+
+  describe("clearToolHistory", () => {
+    test("clears history so subsequent calls start fresh", async () => {
+      // Build up history
+      for (let i = 0; i < 10; i++) {
+        await checkToolLoop(SESSION_KEY, "Read", { file_path: "/same.ts" });
+      }
+
+      // Clear
+      await clearToolHistory(SESSION_KEY);
+
+      // Next call should be clean (below threshold)
+      const result = await checkToolLoop(SESSION_KEY, "Read", { file_path: "/same.ts" });
+      expect(result.blocked).toBe(false);
+      expect(result.severity).toBeUndefined();
+    });
+  });
+
+  describe("hashArgs — determinism", () => {
+    test("identical args produce same detection behavior regardless of key order", async () => {
+      // Call with keys in different order — should be treated the same
+      await clearToolHistory(SESSION_KEY);
+
+      for (let i = 0; i < 8; i++) {
+        // Alternate key order
+        if (i % 2 === 0) {
+          await checkToolLoop(SESSION_KEY, "Edit", { file_path: "/a.ts", old_string: "x" });
+        } else {
+          await checkToolLoop(SESSION_KEY, "Edit", { old_string: "x", file_path: "/a.ts" });
+        }
+      }
+
+      // Should trigger warning since hashArgs sorts keys — all 8 calls are identical
+      const result = await checkToolLoop(SESSION_KEY, "Edit", {
+        file_path: "/a.ts",
+        old_string: "x",
+      });
+      expect(result.severity).toBe("warning");
+    });
+  });
+});

package/src/hooks/tool-loop-detection.ts

@@ -0,0 +1,167 @@
+/**
+ * Tool loop detection for agent-swarm hooks.
+ *
+ * Tracks recent tool calls per session and detects repetitive patterns.
+ * Uses a file-based history to persist across hook invocations (hooks are
+ * separate Bun processes, not long-running).
+ */
+
+interface ToolCallRecord {
+  toolName: string;
+  argsHash: string;
+  timestamp: number;
+}
+
+interface LoopDetectionResult {
+  blocked: boolean;
+  reason?: string;
+  severity?: "warning" | "critical";
+}
+
+const HISTORY_DIR = "/tmp/agent-swarm-tool-history";
+const MAX_HISTORY = 30; // Sliding window size
+const REPEAT_WARNING_THRESHOLD = 8;
+const REPEAT_CRITICAL_THRESHOLD = 15;
+const PINGPONG_WARNING_THRESHOLD = 6;
+const PINGPONG_CRITICAL_THRESHOLD = 12;
+
+/**
+ * Simple hash of tool arguments for comparison.
+ * Uses JSON.stringify + a basic hash to avoid storing full args.
+ */
+function hashArgs(args: Record<string, unknown>): string {
+  const str = JSON.stringify(args, Object.keys(args).sort());
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash |= 0; // Convert to 32bit integer
+  }
+  return hash.toString(36);
+}
+
+/**
+ * Load tool call history for a session.
+ */
+async function loadHistory(sessionKey: string): Promise<ToolCallRecord[]> {
+  try {
+    const file = Bun.file(`${HISTORY_DIR}/${sessionKey}.json`);
+    if (await file.exists()) {
+      return await file.json();
+    }
+  } catch {
+    // Corrupted or missing file — start fresh
+  }
+  return [];
+}
+
+/**
+ * Save tool call history for a session.
+ */
+async function saveHistory(sessionKey: string, history: ToolCallRecord[]): Promise<void> {
+  try {
+    await Bun.$`mkdir -p ${HISTORY_DIR}`.quiet();
+    await Bun.write(
+      `${HISTORY_DIR}/${sessionKey}.json`,
+      JSON.stringify(history.slice(-MAX_HISTORY)),
+    );
+  } catch {
+    // Non-critical — best effort persistence
+  }
+}
+
+/**
+ * Detect if the current tool call is part of a repetitive loop.
+ */
+export async function checkToolLoop(
+  sessionKey: string,
+  toolName: string,
+  toolInput: Record<string, unknown>,
+): Promise<LoopDetectionResult> {
+  const argsHash = hashArgs(toolInput);
+  const history = await loadHistory(sessionKey);
+
+  // Add current call to history
+  history.push({ toolName, argsHash, timestamp: Date.now() });
+  await saveHistory(sessionKey, history);
+
+  // Only check if we have enough history
+  if (history.length < REPEAT_WARNING_THRESHOLD) {
+    return { blocked: false };
+  }
+
+  // Strategy 1: Same tool + same args repeated
+  const key = `${toolName}:${argsHash}`;
+  let repeatCount = 0;
+  for (const record of history) {
+    if (`${record.toolName}:${record.argsHash}` === key) {
+      repeatCount++;
+    }
+  }
+
+  if (repeatCount >= REPEAT_CRITICAL_THRESHOLD) {
+    return {
+      blocked: true,
+      severity: "critical",
+      reason: `Tool "${toolName}" has been called ${repeatCount} times with identical arguments in the last ${MAX_HISTORY} calls. You are stuck in a loop. Try a completely different approach.`,
+    };
+  }
+
+  if (repeatCount >= REPEAT_WARNING_THRESHOLD) {
+    return {
+      blocked: false,
+      severity: "warning",
+      reason: `Tool "${toolName}" has been called ${repeatCount} times with identical arguments. Consider trying a different approach.`,
+    };
+  }
+
+  // Strategy 2: Ping-pong between two tool call patterns
+  if (history.length >= PINGPONG_WARNING_THRESHOLD) {
+    const recent = history.slice(-PINGPONG_CRITICAL_THRESHOLD);
+    const patterns = new Map<string, number>();
+    for (const r of recent) {
+      const p = `${r.toolName}:${r.argsHash}`;
+      patterns.set(p, (patterns.get(p) || 0) + 1);
+    }
+
+    // Check if exactly 2 patterns dominate
+    const sorted = [...patterns.entries()].sort((a, b) => b[1] - a[1]);
+    if (sorted.length >= 2) {
+      const [first, second] = sorted;
+      if (first && second) {
+        const dominance = first[1] + second[1];
+        if (dominance >= recent.length * 0.8) {
+          const totalPingPong = first[1] + second[1];
+          if (totalPingPong >= PINGPONG_CRITICAL_THRESHOLD) {
+            return {
+              blocked: true,
+              severity: "critical",
+              reason: `Detected ping-pong loop: alternating between "${first[0].split(":")[0]}" and "${second[0].split(":")[0]}" for ${totalPingPong} calls. Break out of this pattern.`,
+            };
+          }
+          if (totalPingPong >= PINGPONG_WARNING_THRESHOLD) {
+            return {
+              blocked: false,
+              severity: "warning",
+              reason:
+                "Possible ping-pong pattern detected between two tool calls. Consider a different approach.",
+            };
+          }
+        }
+      }
+    }
+  }
+
+  return { blocked: false };
+}
+
+/**
+ * Clear tool call history for a session (call on session end).
+ */
+export async function clearToolHistory(sessionKey: string): Promise<void> {
+  try {
+    await Bun.$`rm -f ${HISTORY_DIR}/${sessionKey}.json`.quiet();
+  } catch {
+    // Non-critical
+  }
+}

package/src/http/active-sessions.ts

@@ -0,0 +1,199 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import {
+  cleanupAgentSessions,
+  cleanupStaleSessions,
+  deleteActiveSession,
+  deleteActiveSessionById,
+  getActiveSessions,
+  heartbeatActiveSession,
+  insertActiveSession,
+  updateActiveSessionProviderSessionId,
+} from "../be/db";
+import { route } from "./route-def";
+import { json } from "./utils";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const listActiveSessions = route({
+  method: "get",
+  path: "/api/active-sessions",
+  pattern: ["api", "active-sessions"],
+  summary: "List active sessions",
+  tags: ["Active Sessions"],
+  query: z.object({
+    agentId: z.string().uuid().optional(),
+  }),
+  responses: {
+    200: { description: "Active session list" },
+  },
+});
+
+const createActiveSession = route({
+  method: "post",
+  path: "/api/active-sessions",
+  pattern: ["api", "active-sessions"],
+  summary: "Create a new active session",
+  tags: ["Active Sessions"],
+  body: z.object({
+    agentId: z.string().min(1),
+    taskId: z.string().optional(),
+    triggerType: z.string().min(1),
+    inboxMessageId: z.string().optional(),
+    taskDescription: z.string().optional(),
+    runnerSessionId: z.string().optional(),
+  }),
+  responses: {
+    201: { description: "Session created" },
+    400: { description: "Validation error" },
+  },
+});
+
+const deleteSessionByTask = route({
+  method: "delete",
+  path: "/api/active-sessions/by-task/{taskId}",
+  pattern: ["api", "active-sessions", "by-task", null],
+  summary: "Delete active session by task ID",
+  tags: ["Active Sessions"],
+  params: z.object({ taskId: z.string() }),
+  responses: {
+    200: { description: "Session deleted" },
+  },
+});
+
+const deleteSessionById = route({
+  method: "delete",
+  path: "/api/active-sessions/{id}",
+  pattern: ["api", "active-sessions", null],
+  summary: "Delete active session by ID",
+  tags: ["Active Sessions"],
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "Session deleted" },
+  },
+});
+
+const heartbeatSession = route({
+  method: "put",
+  path: "/api/active-sessions/heartbeat/{taskId}",
+  pattern: ["api", "active-sessions", "heartbeat", null],
+  summary: "Update heartbeat for an active session",
+  tags: ["Active Sessions"],
+  params: z.object({ taskId: z.string() }),
+  responses: {
+    200: { description: "Heartbeat updated" },
+  },
+});
+
+const updateProviderSession = route({
+  method: "put",
+  path: "/api/active-sessions/provider-session/{taskId}",
+  pattern: ["api", "active-sessions", "provider-session", null],
+  summary: "Update provider session ID on an active session",
+  tags: ["Active Sessions"],
+  params: z.object({ taskId: z.string() }),
+  body: z.object({ providerSessionId: z.string().min(1) }),
+  responses: {
+    200: { description: "Provider session ID updated" },
+  },
+});
+
+const cleanupSessions = route({
+  method: "post",
+  path: "/api/active-sessions/cleanup",
+  pattern: ["api", "active-sessions", "cleanup"],
+  summary: "Clean up stale sessions",
+  tags: ["Active Sessions"],
+  body: z
+    .object({
+      agentId: z.string().optional(),
+      maxAgeMinutes: z.number().int().optional(),
+    })
+    .optional(),
+  responses: {
+    200: { description: "Cleanup result" },
+  },
+});
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleActiveSessions(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+  _myAgentId: string | undefined,
+): Promise<boolean> {
+  if (listActiveSessions.match(req.method, pathSegments)) {
+    const parsed = await listActiveSessions.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const sessions = getActiveSessions(parsed.query.agentId || undefined);
+    json(res, { sessions });
+    return true;
+  }
+
+  if (createActiveSession.match(req.method, pathSegments)) {
+    const parsed = await createActiveSession.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const session = insertActiveSession({
+      agentId: parsed.body.agentId,
+      taskId: parsed.body.taskId,
+      triggerType: parsed.body.triggerType,
+      inboxMessageId: parsed.body.inboxMessageId,
+      taskDescription: parsed.body.taskDescription,
+      runnerSessionId: parsed.body.runnerSessionId,
+    });
+    json(res, { session }, 201);
+    return true;
+  }
+
+  if (deleteSessionByTask.match(req.method, pathSegments)) {
+    const parsed = await deleteSessionByTask.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const deleted = deleteActiveSession(parsed.params.taskId);
+    json(res, { deleted });
+    return true;
+  }
+
+  if (deleteSessionById.match(req.method, pathSegments)) {
+    const parsed = await deleteSessionById.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const deleted = deleteActiveSessionById(parsed.params.id);
+    json(res, { deleted });
+    return true;
+  }
+
+  if (heartbeatSession.match(req.method, pathSegments)) {
+    const parsed = await heartbeatSession.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const updated = heartbeatActiveSession(parsed.params.taskId);
+    json(res, { updated });
+    return true;
+  }
+
+  if (updateProviderSession.match(req.method, pathSegments)) {
+    const parsed = await updateProviderSession.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const updated = updateActiveSessionProviderSessionId(
+      parsed.params.taskId,
+      parsed.body.providerSessionId,
+    );
+    json(res, { updated });
+    return true;
+  }
+
+  if (cleanupSessions.match(req.method, pathSegments)) {
+    const parsed = await cleanupSessions.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    let cleaned = 0;
+    if (parsed.body?.agentId) {
+      cleaned = cleanupAgentSessions(parsed.body.agentId);
+    } else {
+      cleaned = cleanupStaleSessions(parsed.body?.maxAgeMinutes ?? 30);
+    }
+    json(res, { cleaned });
+    return true;
+  }
+
+  return false;
+}