@desplega.ai/agent-swarm 1.74.4 → 1.76.0

package/src/tests/memory-rate-endpoint.test.ts

@@ -0,0 +1,330 @@
+/**
+ * HTTP integration tests for the memory-rater v1.5 worker-facing endpoints:
+ *   POST /api/memory/rate
+ *   GET  /api/memory/retrievals
+ *
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-3.md
+ *
+ * Spawns the API server against an isolated SQLite file, then opens the same
+ * file from the test process for state setup/verification (WAL mode allows
+ * concurrent readers + writers).
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomUUID } from "node:crypto";
+import { unlink } from "node:fs/promises";
+import type { Subprocess } from "bun";
+import { closeDb, createAgent, getDb, initDb } from "../be/db";
+import { SqliteMemoryStore } from "../be/memory/providers/sqlite-store";
+
+const TEST_PORT = 19111;
+const TEST_DB_PATH = `/tmp/test-memory-rate-${Date.now()}.sqlite`;
+const BASE = `http://localhost:${TEST_PORT}`;
+const API_KEY = "test-key";
+
+let serverProc: Subprocess;
+const agentA = randomUUID();
+const agentB = randomUUID();
+const taskA = randomUUID();
+const taskB = randomUUID();
+let store: SqliteMemoryStore;
+
+// preload.ts builds an in-memory migrated DB template that initDb's fast path
+// restores from — fine for single-process tests, but here we need the test
+// process to share a real file-backed DB with the spawned API server. Hide the
+// template across the suite and restore it in afterAll for downstream suites.
+const testTemplateGlobals = globalThis as typeof globalThis & {
+  __testMigrationTemplate?: Uint8Array;
+  __savedRateTemplate?: Uint8Array;
+};
+
+async function api(
+  method: string,
+  path: string,
+  opts: { body?: unknown; agentId?: string } = {},
+  // biome-ignore lint/suspicious/noExplicitAny: test helper
+): Promise<{ status: number; body: any }> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${API_KEY}`,
+  };
+  if (opts.agentId) headers["x-agent-id"] = opts.agentId;
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers,
+    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+  });
+  const text = await res.text();
+  // biome-ignore lint/suspicious/noExplicitAny: body may be JSON or text
+  let body: any;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+  return { status: res.status, body };
+}
+
+async function waitForServer(url: string, timeoutMs = 15000): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const r = await fetch(url);
+      if (r.ok) return;
+    } catch {
+      // not ready
+    }
+    await Bun.sleep(50);
+  }
+  throw new Error(`Server did not start within ${timeoutMs}ms`);
+}
+
+function makeMemory(name: string, agentId = agentA): { id: string } {
+  return store.store({
+    agentId,
+    scope: "agent",
+    name,
+    content: `${name} content`,
+    source: "manual",
+  });
+}
+
+function insertRetrieval(taskId: string, agentId: string, memoryId: string): void {
+  getDb()
+    .prepare(
+      `INSERT INTO memory_retrieval (id, taskId, agentId, sessionId, memoryId, similarity, retrievedAt)
+       VALUES (?, ?, ?, NULL, ?, 0.85, ?)`,
+    )
+    .run(randomUUID(), taskId, agentId, memoryId, new Date().toISOString());
+}
+
+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 };
+}
+
+beforeAll(async () => {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(TEST_DB_PATH + suffix);
+    } catch {}
+  }
+
+  serverProc = Bun.spawn(["bun", "src/http.ts"], {
+    cwd: `${import.meta.dir}/../..`,
+    env: {
+      ...process.env,
+      PORT: String(TEST_PORT),
+      DATABASE_PATH: TEST_DB_PATH,
+      API_KEY,
+      CAPABILITIES: "core",
+      SLACK_BOT_TOKEN: "",
+      LINEAR_DISABLE: "true",
+      JIRA_DISABLE: "true",
+      GITHUB_DISABLE: "true",
+      SLACK_DISABLE: "true",
+      HEARTBEAT_DISABLE: "true",
+      OAUTH_KEEPALIVE_DISABLE: "true",
+      ANONYMIZED_TELEMETRY: "false",
+    },
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+
+  await waitForServer(`${BASE}/health`);
+
+  // Hide preload.ts's in-memory template so initDb opens the real file (the
+  // server already migrated it), giving us cross-process WAL visibility.
+  testTemplateGlobals.__savedRateTemplate = testTemplateGlobals.__testMigrationTemplate;
+  testTemplateGlobals.__testMigrationTemplate = undefined;
+  // Close any leftover in-memory DB from a prior test in the same Bun worker.
+  // initDb is a no-op when `db` is already set, so without this the test
+  // process can keep writing to the previous template-restored DB while the
+  // spawned server reads from TEST_DB_PATH — defensive even if today's CI
+  // ordering happens to leave `db` null here.
+  closeDb();
+  initDb(TEST_DB_PATH);
+  createAgent({ id: agentA, name: "Agent A", isLead: false, status: "idle" });
+  createAgent({ id: agentB, name: "Agent B", isLead: false, status: "idle" });
+
+  const insertTask = getDb().prepare(
+    `INSERT INTO agent_tasks (id, agentId, task, status, source, createdAt, lastUpdatedAt)
+     VALUES (?, ?, ?, 'in_progress', 'mcp', ?, ?)`,
+  );
+  const now = new Date().toISOString();
+  insertTask.run(taskA, agentA, "task A", now, now);
+  insertTask.run(taskB, agentA, "task B", now, now);
+
+  store = new SqliteMemoryStore();
+}, 20000);
+
+afterAll(async () => {
+  closeDb();
+  // Restore preload.ts's template for any subsequent suites.
+  testTemplateGlobals.__testMigrationTemplate = testTemplateGlobals.__savedRateTemplate;
+  testTemplateGlobals.__savedRateTemplate = undefined;
+  if (serverProc) {
+    serverProc.kill();
+    try {
+      await serverProc.exited;
+    } catch {}
+  }
+  await Bun.sleep(50);
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(TEST_DB_PATH + suffix);
+    } catch {}
+  }
+});
+
+beforeEach(() => {
+  // Reset per-test mutable state. agent_memory rows persist across tests;
+  // alpha/beta are reset so each test starts from the Beta(1,1) prior.
+  getDb().run("DELETE FROM memory_rating");
+  getDb().run("DELETE FROM memory_retrieval");
+  getDb().run("UPDATE agent_memory SET alpha = 1.0, beta = 1.0");
+});
+
+describe("POST /api/memory/rate", () => {
+  test("happy path: source=llm with valid memoryId → 200, applied=1, alpha bumped", async () => {
+    const m = makeMemory("rate-llm-1");
+    const r = await api("POST", "/api/memory/rate", {
+      agentId: agentA,
+      body: {
+        events: [{ memoryId: m.id, signal: 1, weight: 1, source: "llm", taskId: taskA }],
+      },
+    });
+    expect(r.status).toBe(200);
+    expect(r.body.applied).toBe(1);
+    expect(r.body.rejected).toEqual([]);
+    expect(readPosterior(m.id).alpha).toBeCloseTo(2, 5);
+  });
+
+  test("source=explicit-self with no retrieval row → 400 (R6 spam guard)", async () => {
+    const m = makeMemory("explicit-no-retr");
+    const r = await api("POST", "/api/memory/rate", {
+      agentId: agentA,
+      body: {
+        events: [{ memoryId: m.id, signal: 1, weight: 1, source: "explicit-self", taskId: taskA }],
+      },
+    });
+    expect(r.status).toBe(400);
+    expect(String(r.body.error)).toMatch(/not present in memory_retrieval/);
+  });
+
+  test("source=explicit-self without taskId → 400", async () => {
+    const m = makeMemory("explicit-no-task");
+    const r = await api("POST", "/api/memory/rate", {
+      agentId: agentA,
+      body: {
+        events: [{ memoryId: m.id, signal: 1, weight: 1, source: "explicit-self" }],
+      },
+    });
+    expect(r.status).toBe(400);
+    expect(String(r.body.error)).toMatch(/requires taskId/);
+  });
+
+  test("source=explicit-self with retrieval row → 200, applied=1", async () => {
+    const m = makeMemory("explicit-ok");
+    insertRetrieval(taskA, agentA, m.id);
+    const r = await api("POST", "/api/memory/rate", {
+      agentId: agentA,
+      body: {
+        events: [{ memoryId: m.id, signal: 1, weight: 1, source: "explicit-self", taskId: taskA }],
+      },
+    });
+    expect(r.status).toBe(200);
+    expect(r.body.applied).toBe(1);
+  });
+
+  test("duplicate explicit-self for same (taskId, memoryId) → 409", async () => {
+    const m = makeMemory("explicit-dup");
+    insertRetrieval(taskA, agentA, m.id);
+    const evt = {
+      memoryId: m.id,
+      signal: 1,
+      weight: 1,
+      source: "explicit-self",
+      taskId: taskA,
+    };
+    const first = await api("POST", "/api/memory/rate", {
+      agentId: agentA,
+      body: { events: [evt] },
+    });
+    expect(first.status).toBe(200);
+    const second = await api("POST", "/api/memory/rate", {
+      agentId: agentA,
+      body: { events: [evt] },
+    });
+    expect(second.status).toBe(409);
+    expect(String(second.body.error)).toMatch(/Duplicate explicit-self/);
+  });
+
+  test("51 events → 400 (cap enforced)", async () => {
+    const m = makeMemory("cap");
+    const events = Array.from({ length: 51 }, () => ({
+      memoryId: m.id,
+      signal: 1,
+      weight: 0.01,
+      source: "llm",
+    }));
+    const r = await api("POST", "/api/memory/rate", {
+      agentId: agentA,
+      body: { events },
+    });
+    expect(r.status).toBe(400);
+  });
+
+  test("source=implicit-citation rejected at HTTP boundary → 400", async () => {
+    const m = makeMemory("impl-cit-spoof");
+    const r = await api("POST", "/api/memory/rate", {
+      agentId: agentA,
+      body: {
+        events: [{ memoryId: m.id, signal: 1, weight: 1, source: "implicit-citation" }],
+      },
+    });
+    expect(r.status).toBe(400);
+  });
+
+  test("missing X-Agent-ID → 400", async () => {
+    const m = makeMemory("no-agent");
+    const r = await api("POST", "/api/memory/rate", {
+      body: { events: [{ memoryId: m.id, signal: 1, weight: 1, source: "llm" }] },
+    });
+    expect(r.status).toBe(400);
+  });
+});
+
+describe("GET /api/memory/retrievals", () => {
+  test("requires taskId or sessionId → 400", async () => {
+    const r = await api("GET", "/api/memory/retrievals", { agentId: agentA });
+    expect(r.status).toBe(400);
+  });
+
+  test("returns rows for the requesting agent only (defence-in-depth)", async () => {
+    const m1 = makeMemory("retr-1");
+    const m2 = makeMemory("retr-2");
+    const mOther = makeMemory("retr-other");
+    insertRetrieval(taskA, agentA, m1.id);
+    insertRetrieval(taskA, agentA, m2.id);
+    insertRetrieval(taskA, agentB, mOther.id); // wrong agent — must NOT leak
+
+    const r = await api("GET", `/api/memory/retrievals?taskId=${taskA}`, {
+      agentId: agentA,
+    });
+    expect(r.status).toBe(200);
+    expect(Array.isArray(r.body.results)).toBe(true);
+    expect(r.body.results).toHaveLength(2);
+    const ids = (r.body.results as { id: string }[]).map((x) => x.id).sort();
+    expect(ids).toEqual([m1.id, m2.id].sort());
+    // Content snippet capped at 500 chars
+    for (const row of r.body.results as { content: string; name: string }[]) {
+      expect(row.content.length).toBeLessThanOrEqual(500);
+      expect(row.name).toMatch(/^retr-/);
+    }
+  });
+});

package/src/tests/memory-rate-tool.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Unit + integration tests for the `memory_rate` MCP tool and the
+ * conditional system-prompt addendum from `src/prompts/memories.ts`.
+ *
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-5.md §7
+ *
+ * Strategy:
+ *   - Tool tests stub `globalThis.fetch` to assert the request payload and
+ *     simulate the 200/400/409 responses the step-3 endpoint emits. No
+ *     network or server boot needed.
+ *   - Prompt tests flip `MEMORY_RATERS` and assert the addendum is gated
+ *     on `explicit-self` being present.
+ *   - MCP handshake test registers the tool against a fresh `McpServer` and
+ *     pulls the entry out of the SDK's registry to confirm the wiring.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { renderMemoriesPrompt } from "../prompts/memories";
+import { registerMemoryRateTool } from "../tools/memory-rate";
+
+type FetchInit = Parameters<typeof fetch>[1];
+type CallRecord = { url: string; init: FetchInit };
+
+const originalFetch = globalThis.fetch;
+
+function installFetchStub(
+  responder: (url: string, init: FetchInit) => Response | Promise<Response>,
+): { calls: CallRecord[] } {
+  const calls: CallRecord[] = [];
+  globalThis.fetch = (async (input: Parameters<typeof fetch>[0], init?: FetchInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : "";
+    calls.push({ url, init: init ?? {} });
+    return responder(url, init ?? {});
+  }) as typeof fetch;
+  return { calls };
+}
+
+function buildServer() {
+  const server = new McpServer({ name: "memory-rate-test", version: "1.0.0" });
+  registerMemoryRateTool(server);
+  type RegisteredTool = {
+    handler: (args: unknown, extra: unknown) => Promise<unknown>;
+  };
+  const registered = (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+    ._registeredTools;
+  const tool = registered.memory_rate;
+  if (!tool) throw new Error("memory_rate tool not registered");
+  return { server, tool, registered };
+}
+
+const fakeMeta = {
+  sessionId: "session-123",
+  requestInfo: {
+    headers: {
+      "x-agent-id": "agent-abc",
+      "x-source-task-id": "11111111-1111-4111-8111-111111111111",
+    },
+  },
+};
+
+const memoryId = "22222222-2222-4222-8222-222222222222";
+
+describe("memory_rate MCP tool", () => {
+  beforeEach(() => {
+    process.env.MCP_BASE_URL = "http://test-host:9999";
+    process.env.API_KEY = "test-key";
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    delete process.env.MCP_BASE_URL;
+    delete process.env.API_KEY;
+  });
+
+  test("success path POSTs the canonical event shape and returns success=true", async () => {
+    const { tool } = buildServer();
+    const { calls } = installFetchStub(() => new Response("{}", { status: 200 }));
+
+    const result = (await tool.handler({ id: memoryId, useful: true }, fakeMeta)) as {
+      structuredContent: { success: boolean; message: string };
+    };
+
+    expect(result.structuredContent.success).toBe(true);
+    expect(result.structuredContent.message).toContain("useful");
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toBe("http://test-host:9999/api/memory/rate");
+    expect(calls[0]!.init?.method).toBe("POST");
+    const headers = calls[0]!.init?.headers as Record<string, string>;
+    expect(headers["X-Agent-ID"]).toBe("agent-abc");
+    expect(headers.Authorization).toBe("Bearer test-key");
+    const body = JSON.parse(calls[0]!.init?.body as string);
+    expect(body).toEqual({
+      events: [
+        {
+          memoryId,
+          signal: 1,
+          weight: 1.0,
+          source: "explicit-self",
+          reasoning: "",
+          taskId: "11111111-1111-4111-8111-111111111111",
+        },
+      ],
+    });
+  });
+
+  test("useful=false flips signal to -1 and forwards the note as reasoning", async () => {
+    const { tool } = buildServer();
+    const { calls } = installFetchStub(() => new Response("{}", { status: 200 }));
+
+    await tool.handler({ id: memoryId, useful: false, note: "actually misleading" }, fakeMeta);
+
+    const body = JSON.parse(calls[0]!.init?.body as string);
+    expect(body.events[0].signal).toBe(-1);
+    expect(body.events[0].reasoning).toBe("actually misleading");
+  });
+
+  test("409 → success=false with the canned duplicate message", async () => {
+    const { tool } = buildServer();
+    installFetchStub(
+      () =>
+        new Response(JSON.stringify({ error: "Duplicate explicit-self" }), {
+          status: 409,
+        }),
+    );
+
+    const result = (await tool.handler({ id: memoryId, useful: true }, fakeMeta)) as {
+      structuredContent: { success: boolean; message: string };
+    };
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toBe(
+      "Memory already rated for this task. Use a follow-up memory_rerate tool (coming soon) to override.",
+    );
+  });
+
+  test("400 → success=false with a clear message and the server error detail", async () => {
+    const { tool } = buildServer();
+    installFetchStub(
+      () =>
+        new Response(
+          JSON.stringify({
+            error: `explicit-self rating rejected: memoryId=${memoryId} not present in memory_retrieval for task=t`,
+          }),
+          { status: 400 },
+        ),
+    );
+
+    const result = (await tool.handler({ id: memoryId, useful: true }, fakeMeta)) as {
+      structuredContent: { success: boolean; message: string };
+    };
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toMatch(/not present in memory_retrieval/);
+    expect(result.structuredContent.message).toMatch(/must have been retrieved/);
+  });
+
+  test("network failure does NOT throw — surfaces a structured error", async () => {
+    const { tool } = buildServer();
+    installFetchStub(() => {
+      throw new Error("connect ECONNREFUSED");
+    });
+
+    const result = (await tool.handler({ id: memoryId, useful: true }, fakeMeta)) as {
+      structuredContent: { success: boolean; message: string };
+    };
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toMatch(/ECONNREFUSED/);
+  });
+
+  test("missing sourceTaskId → tool returns a clear failure without POSTing", async () => {
+    const { tool } = buildServer();
+    const { calls } = installFetchStub(() => new Response("{}", { status: 200 }));
+
+    const noTaskMeta = {
+      sessionId: "session-123",
+      requestInfo: { headers: { "x-agent-id": "agent-abc" } },
+    };
+    const result = (await tool.handler({ id: memoryId, useful: true }, noTaskMeta)) as {
+      structuredContent: { success: boolean; message: string };
+    };
+
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toMatch(/no source task ID/);
+    expect(calls).toHaveLength(0);
+  });
+
+  test("MCP handshake — memory_rate is registered with the expected name", () => {
+    const { registered } = buildServer();
+    expect(Object.keys(registered)).toContain("memory_rate");
+  });
+});
+
+describe("renderMemoriesPrompt — conditional rate-tool hint", () => {
+  const sampleMemories = [
+    { id: "m-1", name: "Foo bug fix", content: "use Bun.serve not express", similarity: 0.9 },
+    { id: "m-2", name: "Low signal", content: "trivial", similarity: 0.1 },
+  ];
+
+  beforeEach(() => {
+    delete process.env.MEMORY_RATERS;
+  });
+
+  afterEach(() => {
+    delete process.env.MEMORY_RATERS;
+  });
+
+  test("no memories above threshold → returns null", () => {
+    const result = renderMemoriesPrompt([{ id: "x", name: "x", content: "x", similarity: 0.1 }]);
+    expect(result).toBeNull();
+  });
+
+  test("MEMORY_RATERS unset → no rate-tool hint (byte-identical to pre-step-5)", () => {
+    const result = renderMemoriesPrompt(sampleMemories);
+    expect(result).not.toBeNull();
+    expect(result).not.toContain("memory_rate");
+    expect(result).toContain("### Relevant Past Knowledge");
+    expect(result).toContain("- **Foo bug fix** (id: m-1):");
+    // Snapshot — exact byte parity with main's runner.ts:1579 block.
+    expect(result).toBe(
+      `\n\n### Relevant Past Knowledge\n\nThese memories from your previous sessions may be useful. Use \`memory-get\` with the memory ID to retrieve full details.\n\n- **Foo bug fix** (id: m-1): use Bun.serve not express\n`,
+    );
+  });
+
+  test("MEMORY_RATERS empty string → no hint", () => {
+    process.env.MEMORY_RATERS = "";
+    const result = renderMemoriesPrompt(sampleMemories);
+    expect(result).not.toContain("memory_rate");
+  });
+
+  test("MEMORY_RATERS=noop → no hint (gate is on explicit-self only)", () => {
+    process.env.MEMORY_RATERS = "noop";
+    const result = renderMemoriesPrompt(sampleMemories);
+    expect(result).not.toContain("memory_rate");
+  });
+
+  test("MEMORY_RATERS=explicit-self → hint appended verbatim", () => {
+    process.env.MEMORY_RATERS = "explicit-self";
+    const result = renderMemoriesPrompt(sampleMemories);
+    expect(result).toContain("memory_rate");
+    expect(result).toContain("trains the swarm to surface better memories");
+    expect(result).toContain("2-5 ratings per task is plenty.");
+  });
+
+  test("MEMORY_RATERS includes explicit-self alongside others → hint appended", () => {
+    process.env.MEMORY_RATERS = "implicit-citation, explicit-self ,llm";
+    const result = renderMemoriesPrompt(sampleMemories);
+    expect(result).toContain("memory_rate");
+  });
+});