@desplega.ai/agent-swarm 1.74.4 → 1.76.0

package/src/tests/memory-rater-store.test.ts

@@ -0,0 +1,249 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, createAgent, getDb, initDb } from "../be/db";
+import { SqliteMemoryStore } from "../be/memory/providers/sqlite-store";
+import { applyRating, ExplicitSelfDuplicateError } from "../be/memory/raters/store";
+import type { RatingEvent } from "../be/memory/raters/types";
+
+const TEST_DB_PATH = "./test-memory-rater-store.sqlite";
+
+describe("applyRating", () => {
+  const agentA = "aaaa0000-0000-4000-8000-000000000001";
+  const taskId = "00000000-0000-4000-8000-000000001234";
+  const taskIdAlt = "00000000-0000-4000-8000-000000abcdef";
+  let store: SqliteMemoryStore;
+
+  beforeAll(async () => {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {}
+    }
+    initDb(TEST_DB_PATH);
+    createAgent({ id: agentA, name: "Test Agent A", isLead: false, status: "idle" });
+    // Real agent_tasks rows so the memory_rating.taskId FK passes.
+    const insertTask = getDb().prepare(
+      `INSERT INTO agent_tasks (id, agentId, task, status, source, createdAt, lastUpdatedAt)
+       VALUES (?, ?, ?, 'in_progress', 'mcp', ?, ?)`,
+    );
+    const nowIso = new Date().toISOString();
+    insertTask.run(taskId, agentA, "test task", nowIso, nowIso);
+    insertTask.run(taskIdAlt, agentA, "test task alt", nowIso, nowIso);
+    store = new SqliteMemoryStore();
+  });
+
+  afterAll(async () => {
+    closeDb();
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {}
+    }
+  });
+
+  beforeEach(() => {
+    // Reset memory_rating between tests so the partial unique index for
+    // explicit-self doesn't leak between cases.
+    getDb().run("DELETE FROM memory_rating");
+    // Reset Beta posteriors to (1,1) so each test starts from the prior.
+    getDb().run("UPDATE agent_memory SET alpha = 1.0, beta = 1.0");
+  });
+
+  function makeMemory(name: string): { id: string } {
+    const memory = store.store({
+      agentId: agentA,
+      scope: "agent",
+      name,
+      content: `${name} content`,
+      source: "manual",
+    });
+    return { id: memory.id };
+  }
+
+  function readPosterior(id: string): { alpha: number; beta: number } {
+    const row = getDb()
+      .prepare<{ alpha: number; beta: number }, [string]>(
+        "SELECT alpha, beta FROM agent_memory WHERE id = ?",
+      )
+      .get(id);
+    if (!row) throw new Error(`memory ${id} not found`);
+    return { alpha: row.alpha, beta: row.beta };
+  }
+
+  function countRatings(memoryId: string): number {
+    const row = getDb()
+      .prepare<{ n: number }, [string]>(
+        "SELECT COUNT(*) AS n FROM memory_rating WHERE memoryId = ?",
+      )
+      .get(memoryId);
+    return row?.n ?? 0;
+  }
+
+  test("signal=+1, weight=1 → alpha += 1, beta += 0; audit row written", () => {
+    const m = makeMemory("positive");
+    const events: RatingEvent[] = [{ memoryId: m.id, signal: 1, weight: 1, source: "test" }];
+    const result = applyRating(events);
+    expect(result.applied).toBe(1);
+    expect(result.rejected).toEqual([]);
+    expect(readPosterior(m.id)).toEqual({ alpha: 2, beta: 1 });
+    expect(countRatings(m.id)).toBe(1);
+  });
+
+  test("signal=-1, weight=0.5 → alpha += 0, beta += 0.5", () => {
+    const m = makeMemory("negative");
+    const result = applyRating([{ memoryId: m.id, signal: -1, weight: 0.5, source: "test" }]);
+    expect(result.applied).toBe(1);
+    expect(readPosterior(m.id)).toEqual({ alpha: 1, beta: 1.5 });
+  });
+
+  test("signal=0 → no posterior movement, audit row still written", () => {
+    const m = makeMemory("neutral");
+    const result = applyRating([{ memoryId: m.id, signal: 0, weight: 1, source: "test" }]);
+    expect(result.applied).toBe(1);
+    expect(readPosterior(m.id)).toEqual({ alpha: 1, beta: 1 });
+    expect(countRatings(m.id)).toBe(1);
+  });
+
+  test("batch of mixed signals applies in one transaction", () => {
+    const a = makeMemory("a");
+    const b = makeMemory("b");
+    const result = applyRating([
+      { memoryId: a.id, signal: 1, weight: 1, source: "rater-x" },
+      { memoryId: b.id, signal: -0.5, weight: 1, source: "rater-x" },
+    ]);
+    expect(result.applied).toBe(2);
+    expect(readPosterior(a.id)).toEqual({ alpha: 2, beta: 1 });
+    expect(readPosterior(b.id)).toEqual({ alpha: 1, beta: 1.5 });
+  });
+
+  test("commutativity: parallel applies sum to deterministic posterior", async () => {
+    const m = makeMemory("hot");
+    const events: RatingEvent[] = Array.from({ length: 20 }, () => ({
+      memoryId: m.id,
+      signal: 1,
+      weight: 0.1,
+      source: "rater-x",
+    }));
+    await Promise.all(events.map((e) => Promise.resolve(applyRating([e]))));
+    const post = readPosterior(m.id);
+    expect(post.alpha).toBeCloseTo(1 + 20 * 0.1, 5);
+    expect(post.beta).toBe(1);
+    expect(countRatings(m.id)).toBe(20);
+  });
+
+  test("out-of-range signal=2 → returned in rejected[], no DB write", () => {
+    const m = makeMemory("oor-signal");
+    const result = applyRating([{ memoryId: m.id, signal: 2, weight: 1, source: "test" }]);
+    expect(result.applied).toBe(0);
+    expect(result.rejected).toHaveLength(1);
+    expect(result.rejected[0]!.reason).toMatch(/signal/);
+    expect(readPosterior(m.id)).toEqual({ alpha: 1, beta: 1 });
+    expect(countRatings(m.id)).toBe(0);
+  });
+
+  test("out-of-range weight=-1 → returned in rejected[], no DB write", () => {
+    const m = makeMemory("oor-weight");
+    const result = applyRating([{ memoryId: m.id, signal: 1, weight: -1, source: "test" }]);
+    expect(result.applied).toBe(0);
+    expect(result.rejected).toHaveLength(1);
+    expect(result.rejected[0]!.reason).toMatch(/weight/);
+    expect(countRatings(m.id)).toBe(0);
+  });
+
+  test("missing memoryId → returned in rejected[], no DB write", () => {
+    const result = applyRating([
+      {
+        memoryId: "00000000-0000-4000-8000-deadbeefdead",
+        signal: 1,
+        weight: 1,
+        source: "test",
+      },
+    ]);
+    expect(result.applied).toBe(0);
+    expect(result.rejected).toHaveLength(1);
+    expect(result.rejected[0]!.reason).toMatch(/not found/i);
+  });
+
+  test("missing source → returned in rejected[]", () => {
+    const m = makeMemory("no-source");
+    const result = applyRating([{ memoryId: m.id, signal: 1, weight: 1, source: "" }]);
+    expect(result.applied).toBe(0);
+    expect(result.rejected).toHaveLength(1);
+    expect(result.rejected[0]!.reason).toMatch(/source/);
+  });
+
+  test("partial batch: invalid events rejected, valid ones applied", () => {
+    const a = makeMemory("a-part");
+    const b = makeMemory("b-part");
+    const result = applyRating([
+      { memoryId: a.id, signal: 1, weight: 1, source: "test" },
+      { memoryId: b.id, signal: 5, weight: 1, source: "test" }, // out of range
+      { memoryId: a.id, signal: -0.5, weight: 0.5, source: "test" },
+    ]);
+    expect(result.applied).toBe(2);
+    expect(result.rejected).toHaveLength(1);
+    expect(readPosterior(a.id)).toEqual({ alpha: 2, beta: 1.25 });
+    expect(readPosterior(b.id)).toEqual({ alpha: 1, beta: 1 });
+  });
+
+  test("explicit-self duplicate raises ExplicitSelfDuplicateError", () => {
+    const m = makeMemory("explicit");
+    const event: RatingEvent = {
+      memoryId: m.id,
+      signal: 1,
+      weight: 1,
+      source: "explicit-self",
+    };
+
+    // First write succeeds.
+    expect(applyRating([event], { taskId }).applied).toBe(1);
+
+    // Second write hits the partial unique index.
+    expect(() => applyRating([event], { taskId })).toThrow(ExplicitSelfDuplicateError);
+
+    // Posterior moved exactly once.
+    expect(readPosterior(m.id)).toEqual({ alpha: 2, beta: 1 });
+  });
+
+  test("empty batch → applied=0, no DB calls, no error", () => {
+    const result = applyRating([]);
+    expect(result).toEqual({ applied: 0, rejected: [] });
+  });
+
+  test("audit row carries source, signal, weight, reasoning, taskId", () => {
+    const m = makeMemory("audit");
+    applyRating(
+      [
+        {
+          memoryId: m.id,
+          signal: 0.7,
+          weight: 0.4,
+          source: "test-rater",
+          reasoning: "because reasons",
+        },
+      ],
+      { taskId: taskIdAlt },
+    );
+    const row = getDb()
+      .prepare<
+        {
+          memoryId: string;
+          taskId: string | null;
+          source: string;
+          signal: number;
+          weight: number;
+          reasoning: string | null;
+        },
+        [string]
+      >(
+        "SELECT memoryId, taskId, source, signal, weight, reasoning FROM memory_rating WHERE memoryId = ?",
+      )
+      .get(m.id);
+    expect(row).not.toBeNull();
+    expect(row!.taskId).toBe(taskIdAlt);
+    expect(row!.source).toBe("test-rater");
+    expect(row!.signal).toBe(0.7);
+    expect(row!.weight).toBe(0.4);
+    expect(row!.reasoning).toBe("because reasons");
+  });
+});

package/src/tests/memory-reranker.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, test } from "bun:test";
-import { accessBoost, computeScore, recencyDecay, rerank } from "../be/memory/reranker";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { accessBoost, computeScore, recencyDecay, rerank, usefulness } from "../be/memory/reranker";
 import type { MemoryCandidate } from "../be/memory/types";
 
 function makeCandidate(
@@ -23,6 +23,8 @@ function makeCandidate(
     accessCount: 0,
     expiresAt: null,
     embeddingModel: null,
+    alpha: 1.0,
+    beta: 1.0,
     ...overrides,
   };
 }
@@ -190,3 +192,160 @@ describe("rerank", () => {
     expect(result1[0]!.similarity).toBe(result2[0]!.similarity);
   });
 });
+
+describe("usefulness", () => {
+  // The default-floor cases assume MEMORY_DEMOTION_FLOOR is unset/empty.
+  // The override case sets and restores the env var.
+  let originalFloor: string | undefined;
+  beforeEach(() => {
+    originalFloor = process.env.MEMORY_DEMOTION_FLOOR;
+    delete process.env.MEMORY_DEMOTION_FLOOR;
+  });
+  afterEach(() => {
+    if (originalFloor === undefined) {
+      delete process.env.MEMORY_DEMOTION_FLOOR;
+    } else {
+      process.env.MEMORY_DEMOTION_FLOOR = originalFloor;
+    }
+  });
+
+  test("Beta(1,1) → exactly 1.0 (default prior is a no-op)", () => {
+    expect(usefulness(1, 1)).toBe(1.0);
+  });
+
+  test("Beta(10,1) → clamp(2 * 10/11, 1, 2) ≈ 1.818", () => {
+    const expected = Math.max(1.0, Math.min(2.0, (2 * 10) / 11));
+    expect(usefulness(10, 1)).toBeCloseTo(expected, 5);
+    expect(usefulness(10, 1)).toBeCloseTo(1.8181818, 5);
+  });
+
+  test("Beta(1,10) → 1.0 (floored at default MEMORY_DEMOTION_FLOOR=1.0)", () => {
+    expect(usefulness(1, 10)).toBe(1.0);
+  });
+
+  test("Beta(50,1) → 2 * 50/51 ≈ 1.961 (approaches ceiling, never above 2.0)", () => {
+    // NB: the clamp `Math.min(2.0, 2 * mean)` is a defensive ceiling — the
+    // formula 2 * α/(α+β) is bounded above by 2 for any finite β > 0, so the
+    // clamp only fires on degenerate inputs (β = 0). The plan's "===2.0"
+    // expectation was a numerical slip; the asymptote is what we ship.
+    expect(usefulness(50, 1)).toBeCloseTo((2 * 50) / 51, 10);
+    expect(usefulness(50, 1)).toBeLessThan(2.0);
+  });
+
+  test("ceiling clamp fires on degenerate β=0 (defensive)", () => {
+    expect(usefulness(10, 0)).toBe(2.0);
+  });
+
+  test("MEMORY_DEMOTION_FLOOR=0.5 lowers the floor and enables demotion", () => {
+    process.env.MEMORY_DEMOTION_FLOOR = "0.5";
+    expect(usefulness(1, 10)).toBe(0.5);
+  });
+});
+
+describe("backward-compat: MEMORY_RATERS unset → reranker is a no-op", () => {
+  // Litmus for step-1: with default Beta(1,1) priors and the default
+  // MEMORY_DEMOTION_FLOOR=1.0, computeScore must return EXACTLY the same value
+  // as a pre-rater build (similarity * recencyDecay * accessBoost).
+  const now = new Date("2026-04-12T12:00:00Z");
+
+  let originalFloor: string | undefined;
+  beforeEach(() => {
+    originalFloor = process.env.MEMORY_DEMOTION_FLOOR;
+    delete process.env.MEMORY_DEMOTION_FLOOR;
+  });
+  afterEach(() => {
+    if (originalFloor === undefined) {
+      delete process.env.MEMORY_DEMOTION_FLOOR;
+    } else {
+      process.env.MEMORY_DEMOTION_FLOOR = originalFloor;
+    }
+  });
+
+  test("computeScore equals similarity * recencyDecay * accessBoost (no usefulness drift)", () => {
+    const cases: MemoryCandidate[] = [
+      makeCandidate({
+        similarity: 0.8,
+        createdAt: now.toISOString(),
+        accessedAt: now.toISOString(),
+        accessCount: 0,
+      }),
+      makeCandidate({
+        similarity: 0.5,
+        createdAt: new Date(now.getTime() - 14 * 86400000).toISOString(),
+        accessedAt: new Date(now.getTime() - 24 * 3600000).toISOString(),
+        accessCount: 5,
+      }),
+      makeCandidate({
+        similarity: 0.99,
+        createdAt: new Date(now.getTime() - 28 * 86400000).toISOString(),
+        accessedAt: new Date(now.getTime() - 72 * 3600000).toISOString(),
+        accessCount: 12,
+      }),
+    ];
+
+    for (const c of cases) {
+      const expected =
+        c.similarity *
+        recencyDecay(c.createdAt, now) *
+        accessBoost(c.accessedAt, c.accessCount, now);
+      expect(computeScore(c, now)).toBe(expected);
+    }
+  });
+
+  test("snapshot order + scores match a hard-coded pre-rater baseline", () => {
+    // Baseline computed from main (pre-step-1): similarity * recencyDecay * accessBoost.
+    // With alpha=beta=1 + default floor, the new code must produce identical numbers.
+    const candidates = [
+      makeCandidate({
+        similarity: 0.9,
+        createdAt: now.toISOString(),
+        accessedAt: now.toISOString(),
+        accessCount: 0,
+      }),
+      makeCandidate({
+        similarity: 0.6,
+        createdAt: new Date(now.getTime() - 7 * 86400000).toISOString(),
+        accessedAt: now.toISOString(),
+        accessCount: 0,
+      }),
+      makeCandidate({
+        similarity: 0.3,
+        createdAt: new Date(now.getTime() - 28 * 86400000).toISOString(),
+        accessedAt: now.toISOString(),
+        accessCount: 0,
+      }),
+    ];
+    const result = rerank(candidates, { limit: 3, now });
+
+    // Expected scores: similarity * 2^(-ageDays/14) (no access boost, alpha=beta=1).
+    // 0.9 * 1.0      = 0.9
+    // 0.6 * 2^(-0.5) ≈ 0.4242640687
+    // 0.3 * 2^(-2)   = 0.075
+    expect(result[0]!.similarity).toBeCloseTo(0.9, 10);
+    expect(result[1]!.similarity).toBeCloseTo(0.6 * 2 ** -0.5, 10);
+    expect(result[2]!.similarity).toBeCloseTo(0.075, 10);
+  });
+
+  test("usefulness multiplies into score when posteriors move", () => {
+    // Sanity: a memory with α=10, β=1 should score ~1.818× higher than the same
+    // memory at α=β=1, holding everything else constant. Other rows unchanged.
+    const proven = makeCandidate({
+      similarity: 0.5,
+      createdAt: now.toISOString(),
+      accessedAt: now.toISOString(),
+      accessCount: 0,
+      alpha: 10,
+      beta: 1,
+    });
+    const baseline = makeCandidate({
+      similarity: 0.5,
+      createdAt: now.toISOString(),
+      accessedAt: now.toISOString(),
+      accessCount: 0,
+    });
+    expect(computeScore(proven, now) / computeScore(baseline, now)).toBeCloseTo(
+      usefulness(10, 1),
+      10,
+    );
+  });
+});

package/src/tests/migration-runner-regressions.test.ts

@@ -71,7 +71,12 @@ describe("migration regressions", () => {
     expect(columns).toContain("setupScript");
   });
 
-  test("fresh DB preserves source CHECK constraint on agent_tasks", () => {
+  test("fresh DB drops source CHECK constraint on agent_tasks (Zod is the gate)", () => {
+    // Migration 056 removes the SQL CHECK on agent_tasks.source — the Zod
+    // `AgentTaskSourceSchema` in src/types.ts is now the single source of
+    // truth for the allowed enum, and is enforced at the HTTP/MCP ingress.
+    // Direct SQL inserts no longer fail on unknown sources by design;
+    // adding a new source no longer requires a forward-only migration.
     const database = initDb(FRESH_DB_PATH);
     const now = new Date().toISOString();
 
@@ -81,6 +86,16 @@ describe("migration regressions", () => {
          VALUES (?, ?, ?, ?, ?, ?)`,
         [crypto.randomUUID(), "invalid source", "pending", "not-valid", now, now],
       );
-    }).toThrow();
+    }).not.toThrow();
+
+    // The requestedByUserId FK survives the table-rebuild in migration 056.
+    const fkList = database
+      .prepare<{ table: string; from: string; to: string }, []>(
+        'SELECT "table" as "table", "from", "to" FROM pragma_foreign_key_list(\'agent_tasks\')',
+      )
+      .all();
+    const requestedByFk = fkList.find((fk) => fk.from === "requestedByUserId");
+    expect(requestedByFk?.table).toBe("users");
+    expect(requestedByFk?.to).toBe("id");
   });
 });

package/src/tests/mocks/mock-llm-rater-client.ts

@@ -0,0 +1,35 @@
+/**
+ * Deterministic in-memory `LlmRaterClient` for tests.
+ *
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-4.md §5
+ *
+ * Used by `memory-rater-llm.test.ts` (this step) and reused by the cross-
+ * cutting e2e in step-7. Keep it dependency-free and side-effect-free.
+ */
+import type {
+  LlmRaterClient,
+  LlmRaterInput,
+  LlmRaterResult,
+} from "../../be/memory/raters/llm-client";
+
+export type MockResultMap = Record<string, LlmRaterResult | null>;
+
+export class MockLlmRaterClient implements LlmRaterClient {
+  /** Inputs received, in call order — for assertions. */
+  public readonly calls: LlmRaterInput[] = [];
+
+  /**
+   * @param map  memoryId → fixed result. Missing keys → fallback.
+   * @param fallback  result returned when a memoryId is not in the map.
+   *                  `null` simulates an LLM parse-failure (skip rating).
+   */
+  constructor(
+    private readonly map: MockResultMap,
+    private readonly fallback: LlmRaterResult | null = null,
+  ) {}
+
+  async rate(input: LlmRaterInput): Promise<LlmRaterResult | null> {
+    this.calls.push(input);
+    return Object.hasOwn(this.map, input.memory.id) ? this.map[input.memory.id] : this.fallback;
+  }
+}