@desplega.ai/agent-swarm 1.74.4 → 1.76.0

package/src/be/memory/edges-store.ts

@@ -0,0 +1,69 @@
+/**
+ * Read-side query helpers for the `agent_memory_edge` table.
+ *
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-6.md §7
+ *
+ * The write path lives in `src/be/memory/raters/store.ts` (`applyRating`
+ * UPSERTs the edge atomically with the memory's posterior update). This
+ * module surfaces reads to the GET `/api/memory/edges` endpoint that powers
+ * the homepage demo ("this memory references PR #377").
+ *
+ * Server-side only.
+ */
+import { getDb } from "@/be/db";
+
+const USEFULNESS_FLOOR = 1.0;
+const USEFULNESS_CEILING = 2.0;
+
+export type MemoryEdgeRow = {
+  to: string;
+  type: "references-source";
+  alpha: number;
+  beta: number;
+  /** clamp(2 * α/(α+β), 1.0, 2.0) — same formula as the memory reranker. */
+  usefulness: number;
+  createdAt: string;
+};
+
+/**
+ * List edges for a memory, with defence-in-depth: the joined `agent_memory`
+ * row must either be swarm-scope or owned by the requesting agent. Returns
+ * `[]` when the memory does not exist or is not visible to the agent — same
+ * shape as a memory with no edges, since neither case has anything useful
+ * to surface to the caller.
+ */
+export function listEdgesForAgent(agentId: string, memoryId: string): MemoryEdgeRow[] {
+  const db = getDb();
+  const memory = db
+    .prepare<{ scope: string; agentId: string | null }, [string]>(
+      "SELECT scope, agentId FROM agent_memory WHERE id = ?",
+    )
+    .get(memoryId);
+  if (!memory) return [];
+  if (memory.scope !== "swarm" && memory.agentId !== agentId) return [];
+
+  const rows = db
+    .prepare<{ to_id: string; alpha: number; beta: number; createdAt: string }, [string]>(
+      `SELECT to_id, alpha, beta, createdAt
+         FROM agent_memory_edge
+        WHERE from_id = ? AND type = 'references-source'
+        ORDER BY createdAt DESC`,
+    )
+    .all(memoryId);
+
+  return rows.map((row) => ({
+    to: row.to_id,
+    type: "references-source" as const,
+    alpha: row.alpha,
+    beta: row.beta,
+    usefulness: clampUsefulness(row.alpha, row.beta),
+    createdAt: row.createdAt,
+  }));
+}
+
+function clampUsefulness(alpha: number, beta: number): number {
+  const denom = alpha + beta;
+  if (denom <= 0) return USEFULNESS_FLOOR;
+  const mean = alpha / denom;
+  return Math.max(USEFULNESS_FLOOR, Math.min(USEFULNESS_CEILING, 2 * mean));
+}

package/src/be/memory/providers/sqlite-store.ts

@@ -30,6 +30,8 @@ type AgentMemoryRow = {
   expiresAt: string | null;
   accessCount: number;
   embeddingModel: string | null;
+  alpha: number;
+  beta: number;
 };
 
 function rowToAgentMemory(row: AgentMemoryRow): AgentMemory {
@@ -61,6 +63,8 @@ function rowToCandidate(row: AgentMemoryRow, similarity: number): MemoryCandidat
     accessCount: row.accessCount ?? 0,
     expiresAt: row.expiresAt ?? null,
     embeddingModel: row.embeddingModel ?? null,
+    alpha: row.alpha ?? 1.0,
+    beta: row.beta ?? 1.0,
   };
 }
 

package/src/be/memory/raters/explicit-self.ts

@@ -0,0 +1,22 @@
+import type { MemoryRater, RatingEvent } from "./types";
+
+/**
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-5.md §3
+ *
+ * Explicit-self rater — registry sentinel only. Never auto-fires from
+ * `applyRating`. Its `RatingEvent`s arrive exclusively through the worker-side
+ * `memory_rate` MCP tool, which POSTs to `/api/memory/rate` with
+ * `source: "explicit-self"`.
+ *
+ * The class exists so `MEMORY_RATERS=explicit-self` can register the name —
+ * which (per step-5.md §5) unlocks the conditional system-prompt hint that
+ * teaches the agent to call `memory_rate`. Stays out of `SERVER_RATERS` so
+ * the store-progress hook never invokes it.
+ */
+export class ExplicitSelfRatingRater implements MemoryRater {
+  readonly name = "explicit-self";
+
+  async rate(): Promise<RatingEvent[]> {
+    return [];
+  }
+}

package/src/be/memory/raters/implicit-citation.ts

@@ -0,0 +1,44 @@
+import type { MemoryRater, RatingContext, RatingEvent } from "./types";
+
+/**
+ * Implicit-citation rater — pure ID-grep over `evidence`.
+ *
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-2.md §4
+ *
+ * For each `memoryId` in `ctx.retrievedMemoryIds`:
+ *   - if `ctx.evidence` contains the literal `memoryId` → +1 weight=0.5
+ *     (positive citation; the agent referenced the memory's id somewhere
+ *     in the task's `session_logs`).
+ *   - else → -1 weight=0.25 (miss; we surfaced this memory but the agent
+ *     did not cite it. Negative signal carries less confidence per
+ *     IR convention from research §3.A and brainstorm Q4).
+ *
+ * The framework (`applyRating` in ./store.ts) sets `event.source` from the
+ * rater's `name`. This rater MUST NOT populate `source` itself — `applyRating`
+ * rejects rater-set sources to defend against rater spoofing.
+ *
+ * Match semantics: literal substring match using `String.prototype.includes`.
+ * If two memory IDs share a prefix (e.g. `mem-A` is a prefix of `mem-AB`),
+ * citing `mem-AB` will count as a hit for both. UUIDs (the production case)
+ * never collide so this is benign; the unit tests lock the behaviour in.
+ *
+ * Pure / deterministic / no DB I/O.
+ */
+export class ImplicitCitationRater implements MemoryRater {
+  readonly name = "implicit-citation";
+
+  async rate(ctx: RatingContext): Promise<RatingEvent[]> {
+    if (ctx.retrievedMemoryIds.length === 0) return [];
+    const evidence = ctx.evidence ?? "";
+
+    const events: RatingEvent[] = [];
+    for (const memoryId of ctx.retrievedMemoryIds) {
+      if (evidence.length > 0 && evidence.includes(memoryId)) {
+        events.push({ memoryId, signal: 1, weight: 0.5, source: "" });
+      } else {
+        events.push({ memoryId, signal: -1, weight: 0.25, source: "" });
+      }
+    }
+    return events;
+  }
+}

package/src/be/memory/raters/llm-client.ts

@@ -0,0 +1,172 @@
+/**
+ * `LlmRaterClient` — pluggable LLM driver used by `LlmRater` to score the
+ * usefulness of a single retrieved memory against a (query, response) pair.
+ *
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-4.md §1
+ *
+ * This module is imported from worker-side `src/hooks/hook.ts` (the session-
+ * summary piggyback path), so it MUST NOT touch `bun:sqlite` or `src/be/db`.
+ * The DB-boundary check in `scripts/check-db-boundary.sh` enforces this.
+ *
+ * Default implementation shells out to the same `claude -p` CLI the hook
+ * already uses for session summarization — zero new SDK dependencies.
+ */
+
+export type LlmRaterInput = {
+  /** What the agent asked the memory system for. */
+  query: string;
+  /** The memory we're scoring. */
+  memory: {
+    id: string;
+    name: string;
+    content: string;
+  };
+  /** The agent's eventual response (or session summary) — the "did this help?" signal. */
+  response: string;
+};
+
+export type LlmRaterResult = {
+  /** Usefulness score in [0, 1]. 0 = misleading, 1 = highly useful. */
+  score: number;
+  /** Short human-readable explanation. */
+  reasoning: string;
+};
+
+export interface LlmRaterClient {
+  /**
+   * Score one memory. Returns null on parse failure / non-JSON output / timeout
+   * — the caller (`LlmRater`) treats `null` as "skip this rating", no posterior
+   * change. Implementations MUST NOT throw on transport errors; swallow + log
+   * + return null so the worker hook can never crash on rater failure.
+   */
+  rate(input: LlmRaterInput): Promise<LlmRaterResult | null>;
+}
+
+/**
+ * Configuration for the Claude-CLI implementation.
+ */
+export type ClaudeCliLlmRaterClientOptions = {
+  /** Override the model. Defaults to `MEMORY_LLM_RATER_MODEL` env var or "haiku". */
+  model?: string;
+  /** Soft timeout (ms) for the `claude -p` shell-out. Default 30s. */
+  timeoutMs?: number;
+};
+
+const DEFAULT_TIMEOUT_MS = 30000;
+
+const PROMPT_TEMPLATE = `You are scoring the usefulness of one retrieved memory.
+
+Return ONLY a JSON object with these fields (no prose, no markdown):
+{
+  "score": number,        // 0 = misleading/unhelpful, 1 = highly useful
+  "reasoning": string     // 1..500 chars, why
+}
+
+QUERY:
+\${query}
+
+MEMORY:
+id: \${memoryId}
+name: \${memoryName}
+content: \${memoryContent}
+
+AGENT RESPONSE / SUMMARY:
+\${response}
+
+Score 0..1.`;
+
+/**
+ * `claude -p --output-format json` returns a JSON envelope of the shape
+ * `{ result: string, ... }`. We parse the envelope, then JSON-parse the
+ * inner `result` to recover the score+reasoning object.
+ */
+type ClaudeCliEnvelope = { result?: unknown };
+
+function buildPrompt(input: LlmRaterInput): string {
+  return PROMPT_TEMPLATE.replace("${query}", input.query)
+    .replace("${memoryId}", input.memory.id)
+    .replace("${memoryName}", input.memory.name)
+    .replace("${memoryContent}", input.memory.content)
+    .replace("${response}", input.response);
+}
+
+function parseScoreAndReasoning(raw: unknown): LlmRaterResult | null {
+  if (typeof raw !== "string") return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw.trim());
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed as { score?: unknown; reasoning?: unknown };
+  const score = typeof obj.score === "number" ? obj.score : null;
+  const reasoning = typeof obj.reasoning === "string" ? obj.reasoning : null;
+  if (score == null || reasoning == null) return null;
+  if (!Number.isFinite(score) || score < 0 || score > 1) return null;
+  if (reasoning.length === 0 || reasoning.length > 500) return null;
+  return { score, reasoning };
+}
+
+export class ClaudeCliLlmRaterClient implements LlmRaterClient {
+  private readonly model: string;
+  private readonly timeoutMs: number;
+
+  constructor(opts: ClaudeCliLlmRaterClientOptions = {}) {
+    this.model = opts.model ?? process.env.MEMORY_LLM_RATER_MODEL ?? "haiku";
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  async rate(input: LlmRaterInput): Promise<LlmRaterResult | null> {
+    const prompt = buildPrompt(input);
+    const tmpFile = `/tmp/llm-rater-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`;
+
+    let stdout = "";
+    try {
+      await Bun.write(tmpFile, prompt);
+      const proc = Bun.spawn(
+        ["bash", "-c", `cat "${tmpFile}" | claude -p --model ${this.model} --output-format json`],
+        {
+          stdout: "pipe",
+          stderr: "pipe",
+          env: { ...process.env, SKIP_SESSION_SUMMARY: "1" },
+        },
+      );
+      const timeoutId = setTimeout(() => proc.kill(), this.timeoutMs);
+      stdout = await new Response(proc.stdout).text();
+      clearTimeout(timeoutId);
+    } catch (err) {
+      console.error("[memory-rater:llm] claude -p shell-out failed:", (err as Error).message);
+      return null;
+    } finally {
+      try {
+        await Bun.$`rm -f ${tmpFile}`.quiet();
+      } catch {
+        // best-effort
+      }
+    }
+
+    let envelope: ClaudeCliEnvelope;
+    try {
+      envelope = JSON.parse(stdout) as ClaudeCliEnvelope;
+    } catch {
+      return null;
+    }
+    return parseScoreAndReasoning(envelope.result);
+  }
+}
+
+/**
+ * Factory honouring `MEMORY_LLM_RATER_PROVIDER` — defaults to `claude-cli`.
+ * Unknown providers fall back to the Claude CLI default and log a warning so
+ * misconfiguration never crashes the worker.
+ */
+export function getDefaultLlmRaterClient(): LlmRaterClient {
+  const provider = (process.env.MEMORY_LLM_RATER_PROVIDER ?? "claude-cli").trim();
+  if (provider !== "claude-cli") {
+    console.warn(
+      `[memory-rater:llm] Unknown MEMORY_LLM_RATER_PROVIDER "${provider}" — falling back to claude-cli`,
+    );
+  }
+  return new ClaudeCliLlmRaterClient();
+}

package/src/be/memory/raters/llm-summarizer.ts

@@ -0,0 +1,218 @@
+/**
+ * `runMemoryRater` — Stop-hook helper that calls OpenRouter for the combined
+ * session-summary + LLM-rater piggyback prompt and returns a schema-validated
+ * `SummaryWithRatings`.
+ *
+ * Refactored out of `src/hooks/hook.ts` so the rater logic stays out of the
+ * hook (review feedback on PR #450). The hook just calls `runMemoryRater(...)`
+ * and inspects the typed result.
+ *
+ * Worker-safe — uses raw `fetch` + the tolerant JSON parser landed in PR #447.
+ * No `bun:sqlite` / `src/be/db` imports. Boundary script enforces this.
+ */
+import { z } from "zod";
+import { type SummaryWithRatings, SummaryWithRatingsSchema } from "./llm";
+
+/**
+ * Default model used when `MEMORY_RATER_MODEL` is unset. Gemini 3 Flash on
+ * OpenRouter — the only Gemini 3 Flash variant published as of this PR (no
+ * stable non-preview slug exists yet). CLAUDE.md project-wide default.
+ */
+export const DEFAULT_MEMORY_RATER_MODEL = "google/gemini-3-flash-preview";
+
+/**
+ * `response_format.json_schema.name` sent to OpenRouter. Used by some
+ * providers as a tag in their structured-output telemetry — keep it stable
+ * so model behaviour stays comparable across calls.
+ */
+export const MEMORY_RATER_SCHEMA_NAME = "memory_rater_output";
+
+const OPENROUTER_CHAT_COMPLETIONS_URL = "https://openrouter.ai/api/v1/chat/completions";
+
+/**
+ * JSON Schema derived from {@link SummaryWithRatingsSchema}, the source of
+ * truth. Computed once at module load via Zod v4's native `z.toJSONSchema`
+ * (Zod v3's `zod-to-json-schema` is incompatible with the v4 runtime we
+ * pin). The `$schema` key is stripped because OpenRouter / OpenAI strict
+ * json_schema mode rejects unrecognized top-level keys.
+ *
+ * Probed end-to-end against `google/gemini-3-flash-preview` with
+ * `response_format.json_schema.strict: true` — accepted, no rewrite needed.
+ */
+export const MEMORY_RATER_JSON_SCHEMA: Record<string, unknown> = (() => {
+  const schema = z.toJSONSchema(SummaryWithRatingsSchema) as Record<string, unknown>;
+  delete schema.$schema;
+  return schema;
+})();
+
+/**
+ * Resolve the OpenRouter model slug. Reads `MEMORY_RATER_MODEL` from the env;
+ * falls back to {@link DEFAULT_MEMORY_RATER_MODEL}. Self-hosters can pin a
+ * different slug (e.g. `anthropic/claude-haiku-4.5`) without a code change.
+ */
+export function getMemoryRaterModel(env: NodeJS.ProcessEnv = process.env): string {
+  const raw = env.MEMORY_RATER_MODEL;
+  if (typeof raw === "string" && raw.trim().length > 0) return raw.trim();
+  return DEFAULT_MEMORY_RATER_MODEL;
+}
+
+/**
+ * Best-effort parse of a JSON string that may be wrapped in markdown fences
+ * (```json … ``` or plain ``` … ```), have a prose preamble, or both. Returns
+ * the parsed value or `null`. NEVER throws.
+ *
+ * Strategy: try strict parse first. On failure, strip a leading ```json /
+ * ```<lang> / ``` fence + matching trailing ```; on second failure, slice
+ * from the first `{` to the last `}` and retry.
+ *
+ * Originally landed in PR #447 to recover ratings from Haiku's occasional
+ * fenced/preambled output despite `response_format: {type: "json_object"}`.
+ * Restored here to harden the OpenRouter direct-HTTP path against the same
+ * class of provider quirks (Gemini Flash also occasionally fences output).
+ */
+export function tryParseLooseJson(raw: string): unknown {
+  const trimmed = raw.trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // fall through to fence-stripping
+  }
+  const fenced = trimmed.match(/^```[a-zA-Z0-9_-]*\s*\n?([\s\S]*?)\n?```\s*$/);
+  if (fenced?.[1]) {
+    try {
+      return JSON.parse(fenced[1].trim());
+    } catch {
+      // fall through
+    }
+  }
+  const first = trimmed.indexOf("{");
+  const last = trimmed.lastIndexOf("}");
+  if (first !== -1 && last > first) {
+    try {
+      return JSON.parse(trimmed.slice(first, last + 1));
+    } catch {
+      // fall through
+    }
+  }
+  return null;
+}
+
+export type RunMemoryRaterOpts = {
+  /** The fully-built prompt (e.g. from `buildSummaryWithRatingsPrompt`). */
+  prompt: string;
+  /** OpenRouter API key. Caller is responsible for the no-op-when-unset gate. */
+  apiKey: string;
+  /** Model slug override; falls through to {@link getMemoryRaterModel}. */
+  model?: string;
+  /** Injectable for tests — defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+  /**
+   * Bytes to keep when logging unexpected response payloads. Capped to avoid
+   * leaking very large bodies into stderr.
+   */
+  responseLogCap?: number;
+};
+
+export type RunMemoryRaterResult =
+  | { ok: true; data: SummaryWithRatings; model: string }
+  | {
+      ok: false;
+      reason: "transport" | "http_error" | "empty_content" | "parse" | "schema";
+      status?: number;
+    };
+
+/**
+ * Call OpenRouter's chat completions endpoint with `response_format` =
+ * `json_object`, then parse and schema-validate the assistant's content.
+ *
+ * Returns a tagged union: `ok: true` with a typed `SummaryWithRatings`, or
+ * `ok: false` with a `reason` discriminator the caller can branch on for
+ * logging. NEVER throws — the hook wraps this in its own try/catch as a
+ * second line of defence, but this function is designed to short-circuit
+ * cleanly rather than propagate exceptions.
+ */
+export async function runMemoryRater(opts: RunMemoryRaterOpts): Promise<RunMemoryRaterResult> {
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const model = opts.model ?? getMemoryRaterModel();
+  const responseLogCap = opts.responseLogCap ?? 200;
+
+  let res: Response;
+  try {
+    res = await fetchFn(OPENROUTER_CHAT_COMPLETIONS_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${opts.apiKey}`,
+      },
+      body: JSON.stringify({
+        model,
+        // OpenRouter strict json_schema — forces the provider's structured-
+        // output guardrails on instead of the looser `json_object` mode.
+        // Schema is derived from the same Zod source of truth, so the
+        // request and the post-validation Zod check can't drift.
+        // https://openrouter.ai/docs/guides/features/structured-outputs
+        response_format: {
+          type: "json_schema",
+          json_schema: {
+            name: MEMORY_RATER_SCHEMA_NAME,
+            strict: true,
+            schema: MEMORY_RATER_JSON_SCHEMA,
+          },
+        },
+        messages: [{ role: "user", content: opts.prompt }],
+      }),
+    });
+  } catch (err) {
+    console.error("[memory-rater:llm] runMemoryRater fetch threw:", (err as Error).message);
+    return { ok: false, reason: "transport" };
+  }
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    console.error(
+      `[memory-rater:llm] OpenRouter ${res.status} ${res.statusText}: ${text.slice(0, responseLogCap)}`,
+    );
+    return { ok: false, reason: "http_error", status: res.status };
+  }
+
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch (err) {
+    console.error("[memory-rater:llm] OpenRouter response was not JSON:", (err as Error).message);
+    return { ok: false, reason: "parse" };
+  }
+
+  const content = extractContent(body);
+  if (typeof content !== "string" || content.length === 0) {
+    return { ok: false, reason: "empty_content" };
+  }
+
+  const candidate = tryParseLooseJson(content);
+  if (candidate === null || typeof candidate !== "object") {
+    return { ok: false, reason: "parse" };
+  }
+
+  const parsed = SummaryWithRatingsSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return { ok: false, reason: "schema" };
+  }
+  return { ok: true, data: parsed.data, model };
+}
+
+/**
+ * Pull `choices[0].message.content` out of an OpenRouter chat-completion
+ * response defensively. Returns the string, or `null` when the shape doesn't
+ * match — caller treats that as `empty_content`.
+ */
+function extractContent(body: unknown): string | null {
+  if (!body || typeof body !== "object") return null;
+  const choices = (body as { choices?: unknown }).choices;
+  if (!Array.isArray(choices) || choices.length === 0) return null;
+  const first = choices[0];
+  if (!first || typeof first !== "object") return null;
+  const message = (first as { message?: unknown }).message;
+  if (!message || typeof message !== "object") return null;
+  const content = (message as { content?: unknown }).content;
+  return typeof content === "string" ? content : null;
+}