@desplega.ai/agent-swarm 1.92.1 → 1.92.2

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.92.1",
+    "version": "1.92.2",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.92.1",
+  "version": "1.92.2",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/be/db.ts

@@ -2117,6 +2117,14 @@ export function failTask(id: string, reason: string): AgentTask | null {
         });
       });
     } catch {}
+
+    // Cascade-fail any non-terminal tasks that depend on this one.
+    // The cascade is recursive (transitive closure) and cycle-safe.
+    try {
+      cascadeFailDependents(id, "failed");
+    } catch (err) {
+      console.error("[failTask] cascade-fail dependents error:", err);
+    }
   }
   return row ? rowToAgentTask(row) : null;
 }
@@ -2155,6 +2163,12 @@ export function cancelTask(id: string, reason?: string): AgentTask | null {
         });
       });
     } catch {}
+
+    try {
+      cascadeFailDependents(id, "cancelled");
+    } catch (err) {
+      console.error("[cancelTask] cascade-fail dependents error:", err);
+    }
   }
 
   return row ? rowToAgentTask(row) : null;
@@ -2218,6 +2232,12 @@ export function supersedeTask(
         });
       });
     } catch {}
+
+    try {
+      cascadeFailDependents(id, "superseded");
+    } catch (err) {
+      console.error("[supersedeTask] cascade-fail dependents error:", err);
+    }
   }
 
   return row ? rowToAgentTask(row) : null;
@@ -3390,6 +3410,75 @@ export function checkDependencies(taskId: string): {
   return { ready: blockedBy.length === 0, blockedBy };
 }
 
+/**
+ * Reverse-lookup: find all tasks whose `dependsOn` JSON array contains `parentId`.
+ * Uses SQLite `json_each` to scan the dependsOn column efficiently.
+ * Returns only non-terminal tasks by default (the callers want to cascade-fail
+ * live dependents, not re-process already-finished ones).
+ */
+export function getDependentTasks(
+  parentId: string,
+  opts?: { includeTerminal?: boolean },
+): AgentTask[] {
+  const database = getDb();
+  const rows = database
+    .prepare<AgentTaskRow, [string]>(
+      `SELECT t.*
+       FROM agent_tasks t, json_each(t.dependsOn) AS dep
+       WHERE dep.value = ?`,
+    )
+    .all(parentId);
+
+  const tasks = rows.map(rowToAgentTask);
+  if (opts?.includeTerminal) return tasks;
+  return tasks.filter((t) => !isTerminalTaskStatus(t.status));
+}
+
+export interface CascadeFailResult {
+  taskId: string;
+  taskSubject: string;
+}
+
+/**
+ * Recursively cascade-fail all transitive dependents of a parent task.
+ * Walks the full dependency graph: if A fails, and B depends on A, and C
+ * depends on B, then both B and C are failed.
+ *
+ * Guards against cycles with a visited set. Skips already-terminal tasks.
+ * Returns the list of tasks that were actually cascade-failed (for follow-up
+ * enrichment).
+ */
+export function cascadeFailDependents(
+  parentId: string,
+  parentStatus: string,
+  visited?: Set<string>,
+): CascadeFailResult[] {
+  const seen = visited ?? new Set<string>();
+  if (seen.has(parentId)) return [];
+  seen.add(parentId);
+
+  const dependents = getDependentTasks(parentId);
+  const results: CascadeFailResult[] = [];
+
+  for (const dep of dependents) {
+    if (seen.has(dep.id)) continue;
+
+    const reason = `Blocked dependency ${parentId.slice(0, 8)} was ${parentStatus}`;
+    const failed = failTask(dep.id, reason);
+    if (failed) {
+      results.push({
+        taskId: failed.id,
+        taskSubject: failed.task.slice(0, 120),
+      });
+      // Recurse: this dependent may itself have dependents
+      const transitive = cascadeFailDependents(dep.id, "failed (cascade)", seen);
+      results.push(...transitive);
+    }
+  }
+
+  return results;
+}
+
 // ============================================================================
 // Agent Profile Operations
 // ============================================================================

package/src/be/memory/boot-reembed.ts

@@ -0,0 +1,85 @@
+/**
+ * Startup backfill: detect agent_memory rows with wrong-dimension embeddings
+ * (not 512d) and re-embed them in the background. Runs once per boot,
+ * async/non-blocking, idempotent, no-op when the DB is clean.
+ *
+ * This is the app-level equivalent of a forward-only migration — SQL can't
+ * call OpenAI, so the backfill runs at startup instead.
+ */
+
+import { getDb } from "@/be/db";
+import { EMBEDDING_DIMENSIONS } from "./constants";
+import { getEmbeddingProvider, getMemoryStore } from "./index";
+
+const VECTOR_BYTES = EMBEDDING_DIMENSIONS * Float32Array.BYTES_PER_ELEMENT;
+const BATCH_SIZE = 20;
+const BACKFILL_KV_KEY = "memory:reembed:backfill_complete";
+
+export async function runBootReembed(): Promise<void> {
+  const db = getDb();
+
+  const invalidCount =
+    db
+      .prepare<{ count: number }, []>(
+        `SELECT COUNT(*) as count FROM agent_memory
+       WHERE embedding IS NOT NULL AND length(embedding) != ${VECTOR_BYTES}`,
+      )
+      .get()?.count ?? 0;
+
+  if (invalidCount === 0) {
+    return;
+  }
+
+  const provider = getEmbeddingProvider();
+  const testEmbed = await provider.embed("test");
+  if (!testEmbed) {
+    console.warn(
+      `[boot-reembed] skipped: ${invalidCount} wrong-dimension rows found but no OpenAI key configured`,
+    );
+    return;
+  }
+
+  console.log(`[boot-reembed] starting: ${invalidCount} rows with wrong embedding dimensions`);
+
+  const store = getMemoryStore();
+  const rows = db
+    .prepare<{ id: string; content: string }, []>(
+      `SELECT id, content FROM agent_memory
+       WHERE embedding IS NOT NULL AND length(embedding) != ${VECTOR_BYTES}`,
+    )
+    .all();
+
+  let reembedded = 0;
+  let failed = 0;
+
+  for (let i = 0; i < rows.length; i += BATCH_SIZE) {
+    const batch = rows.slice(i, i + BATCH_SIZE);
+    try {
+      const embeddings = await provider.embedBatch(batch.map((m) => m.content));
+      for (let j = 0; j < embeddings.length; j++) {
+        if (embeddings[j]) {
+          store.updateEmbedding(batch[j]!.id, embeddings[j]!, provider.name);
+          reembedded++;
+        }
+      }
+    } catch (err) {
+      failed += batch.length;
+      console.error(
+        `[boot-reembed] batch ${Math.floor(i / BATCH_SIZE) + 1} failed:`,
+        (err as Error).message,
+      );
+    }
+  }
+
+  const afterInvalid =
+    db
+      .prepare<{ count: number }, []>(
+        `SELECT COUNT(*) as count FROM agent_memory
+       WHERE embedding IS NOT NULL AND length(embedding) != ${VECTOR_BYTES}`,
+      )
+      .get()?.count ?? 0;
+
+  console.log(
+    `[boot-reembed] complete: reembedded=${reembedded} failed=${failed} remaining_invalid=${afterInvalid}`,
+  );
+}

package/src/be/memory/constants.ts

@@ -15,8 +15,46 @@ export const TTL_DEFAULTS: Record<AgentMemorySource, number | null> = {
   manual: null,
 };
 
+// Per-source recency decay half-life (in days).
+// manual = Infinity (no decay — curated knowledge stays relevant forever).
+// A global MEMORY_RECENCY_HALF_LIFE_DAYS override forces ALL sources to the same value.
+const GLOBAL_HALF_LIFE_OVERRIDE = process.env.MEMORY_RECENCY_HALF_LIFE_DAYS;
+const GLOBAL_HALF_LIFE =
+  GLOBAL_HALF_LIFE_OVERRIDE != null && GLOBAL_HALF_LIFE_OVERRIDE !== ""
+    ? Number(GLOBAL_HALF_LIFE_OVERRIDE)
+    : null;
+
+export const RECENCY_DECAY_HALF_LIFE: Record<AgentMemorySource, number> =
+  GLOBAL_HALF_LIFE != null && Number.isFinite(GLOBAL_HALF_LIFE)
+    ? {
+        manual: GLOBAL_HALF_LIFE,
+        file_index: GLOBAL_HALF_LIFE,
+        task_completion: GLOBAL_HALF_LIFE,
+        session_summary: GLOBAL_HALF_LIFE,
+      }
+    : {
+        manual: Number.POSITIVE_INFINITY,
+        file_index: 180,
+        task_completion: 14,
+        session_summary: 7,
+      };
+
+// Legacy export — callers that don't have a source fall back to task_completion's value.
+export const RECENCY_DECAY_HALF_LIFE_DAYS = RECENCY_DECAY_HALF_LIFE.task_completion;
+
+// Source-quality multiplier for reranking.
+// Curated manual memories rank higher; ephemeral session summaries rank lower.
+export const SOURCE_QUALITY_MULTIPLIER: Record<AgentMemorySource, number> = {
+  manual: 1.5,
+  file_index: 1.0,
+  task_completion: 0.7,
+  session_summary: 0.5,
+};
+
+// Minimum raw cosine similarity to keep a candidate. Below this, the result is noise.
+export const MIN_SIMILARITY = numEnv("MEMORY_MIN_SIMILARITY", 0.1);
+
 // Reranking parameters
-export const RECENCY_DECAY_HALF_LIFE_DAYS = numEnv("MEMORY_RECENCY_HALF_LIFE_DAYS", 14);
 export const ACCESS_BOOST_MAX_MULTIPLIER = numEnv("MEMORY_ACCESS_BOOST_MAX", 1.5);
 export const ACCESS_BOOST_RECENCY_WINDOW_HOURS = numEnv("MEMORY_ACCESS_RECENCY_HOURS", 48);
 export const CANDIDATE_SET_MULTIPLIER = numEnv("MEMORY_CANDIDATE_MULTIPLIER", 3);
@@ -25,3 +63,6 @@ export const CANDIDATE_SET_MULTIPLIER = numEnv("MEMORY_CANDIDATE_MULTIPLIER", 3)
 export const EMBEDDING_DIMENSIONS = numEnv("EMBEDDING_DIMENSIONS", 512);
 export const DEFAULT_EMBEDDING_DIMENSIONS = EMBEDDING_DIMENSIONS;
 export const DEFAULT_EMBEDDING_MODEL = "openai/text-embedding-3-small";
+
+// Manual memories must NEVER be deleted by automated processes (curator, GC, etc.)
+export const PROTECTED_SOURCES: ReadonlySet<AgentMemorySource> = new Set(["manual"]);

package/src/be/memory/providers/openai-embedding.ts

@@ -55,6 +55,13 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
       const values = response.data[0]?.embedding;
       if (!values) return null;
 
+      if (values.length !== this.dimensions) {
+        console.error(
+          `[memory] Embedding dimension mismatch: expected=${this.dimensions} got=${values.length}. Provider may not support the 'dimensions' parameter.`,
+        );
+        return null;
+      }
+
       return new Float32Array(values);
     } catch (err) {
       console.error("[memory] Embedding failed:", (err as Error).message);
@@ -90,6 +97,12 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
       for (const item of response.data) {
         const originalIndex = nonEmptyIndices[item.index];
         if (originalIndex !== undefined && item.embedding) {
+          if (item.embedding.length !== this.dimensions) {
+            console.error(
+              `[memory] Batch embedding dimension mismatch: expected=${this.dimensions} got=${item.embedding.length}. Provider may not support the 'dimensions' parameter.`,
+            );
+            continue;
+          }
           results[originalIndex] = new Float32Array(item.embedding);
         }
       }

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

@@ -1,7 +1,12 @@
 import { getDb, isSqliteVecAvailable } from "@/be/db";
 import { cosineSimilarity, deserializeEmbedding, serializeEmbedding } from "@/be/embedding";
 import type { AgentMemory, AgentMemoryScope, AgentMemorySource } from "@/types";
-import { EMBEDDING_DIMENSIONS, TTL_DEFAULTS } from "../constants";
+import {
+  EMBEDDING_DIMENSIONS,
+  MIN_SIMILARITY,
+  PROTECTED_SOURCES,
+  TTL_DEFAULTS,
+} from "../constants";
 import type {
   MemoryCandidate,
   MemoryHealth,
@@ -400,6 +405,7 @@ export class SqliteMemoryStore implements MemoryStore {
     const candidates: MemoryCandidate[] = [];
     for (const row of rows) {
       const similarity = 1 - row.distance;
+      if (similarity < MIN_SIMILARITY) continue;
       candidates.push(rowToCandidate(row, similarity));
     }
 
@@ -446,6 +452,7 @@ export class SqliteMemoryStore implements MemoryStore {
       const emb = deserializeEmbedding(row.embedding);
       if (emb.length !== queryEmbedding.length) continue;
       const similarity = cosineSimilarity(queryEmbedding, emb);
+      if (similarity < MIN_SIMILARITY) continue;
       candidates.push(rowToCandidate(row, similarity));
     }
 
@@ -523,6 +530,31 @@ export class SqliteMemoryStore implements MemoryStore {
     return rows.map(rowToAgentMemory);
   }
 
+  isSourceProtected(source: AgentMemorySource): boolean {
+    return PROTECTED_SOURCES.has(source);
+  }
+
+  listForCuration(
+    agentId?: string,
+  ): { id: string; source: string; name: string; createdAt: string }[] {
+    const db = getDb();
+    const protectedList = [...PROTECTED_SOURCES].map((s) => `'${s}'`).join(",");
+    if (agentId) {
+      return db
+        .prepare<{ id: string; source: string; name: string; createdAt: string }, [string]>(
+          `SELECT id, source, name, createdAt FROM agent_memory
+           WHERE agentId = ? AND source NOT IN (${protectedList})`,
+        )
+        .all(agentId);
+    }
+    return db
+      .prepare<{ id: string; source: string; name: string; createdAt: string }, []>(
+        `SELECT id, source, name, createdAt FROM agent_memory
+         WHERE source NOT IN (${protectedList})`,
+      )
+      .all();
+  }
+
   listForReembedding(options?: { agentId?: string }): { id: string; content: string }[] {
     const db = getDb();
     if (options?.agentId) {

package/src/be/memory/reranker.ts

@@ -1,7 +1,10 @@
+import type { AgentMemorySource } from "@/types";
 import {
   ACCESS_BOOST_MAX_MULTIPLIER,
   ACCESS_BOOST_RECENCY_WINDOW_HOURS,
+  RECENCY_DECAY_HALF_LIFE,
   RECENCY_DECAY_HALF_LIFE_DAYS,
+  SOURCE_QUALITY_MULTIPLIER,
 } from "./constants";
 import type { MemoryCandidate, RerankOptions } from "./types";
 
@@ -9,13 +12,16 @@ const MS_PER_DAY = 1000 * 60 * 60 * 24;
 const MS_PER_HOUR = 1000 * 60 * 60;
 
 /**
- * Exponential decay based on age. A memory at exactly HALF_LIFE_DAYS old
- * gets multiplied by 0.5. Fresh memories get ~1.0.
+ * Exponential decay based on age and memory source.
+ * Source-aware: manual memories have no decay (Infinity half-life),
+ * file_index = 180d, task_completion = 14d, session_summary = 7d.
  */
-export function recencyDecay(createdAt: string, now: Date): number {
+export function recencyDecay(createdAt: string, now: Date, source?: AgentMemorySource): number {
+  const halfLife = source ? RECENCY_DECAY_HALF_LIFE[source] : RECENCY_DECAY_HALF_LIFE_DAYS;
+  if (!Number.isFinite(halfLife)) return 1.0;
   const ageDays = (now.getTime() - new Date(createdAt).getTime()) / MS_PER_DAY;
   if (ageDays <= 0) return 1.0;
-  return 2 ** (-ageDays / RECENCY_DECAY_HALF_LIFE_DAYS);
+  return 2 ** (-ageDays / halfLife);
 }
 
 /**
@@ -31,6 +37,14 @@ export function accessBoost(accessedAt: string, accessCount: number, now: Date):
   return boost;
 }
 
+/**
+ * Source-quality multiplier. Manual memories get a 1.5× boost,
+ * session summaries get 0.5×. Unknown sources default to 1.0.
+ */
+export function sourceQuality(source: AgentMemorySource): number {
+  return SOURCE_QUALITY_MULTIPLIER[source] ?? 1.0;
+}
+
 /**
  * Beta-Binomial usefulness factor for reranking.
  *
@@ -56,33 +70,37 @@ export function usefulness(alpha: number, beta: number): number {
 }
 
 /**
- * Final score combining similarity, recency decay, access boost, and
- * Beta-Binomial usefulness. With default Beta(1,1) and default
- * MEMORY_DEMOTION_FLOOR=1.0, the usefulness factor is exactly 1.0 and this
- * computation matches the pre-rater behaviour byte-for-byte.
- *
- * v2: optional edge-aware boost — see thoughts/taras/plans/2026-05-05-memory-rater-v1.5/root.md
+ * Final score combining similarity, recency decay, access boost,
+ * source quality, and Beta-Binomial usefulness.
  */
 export function computeScore(candidate: MemoryCandidate, now: Date): number {
   return (
     candidate.similarity *
-    recencyDecay(candidate.createdAt, now) *
+    recencyDecay(candidate.createdAt, now, candidate.source) *
     accessBoost(candidate.accessedAt, candidate.accessCount, now) *
+    sourceQuality(candidate.source) *
     usefulness(candidate.alpha, candidate.beta)
   );
 }
 
 /**
- * Rerank candidates by combining similarity with recency and access signals.
- * Returns the top `limit` candidates sorted by final score.
+ * Rerank candidates by combining similarity with recency, source quality,
+ * and access signals. Returns the top `limit` candidates sorted by composite
+ * score. Preserves raw similarity in `rawSimilarity` and sets `compositeScore`.
  */
 export function rerank(candidates: MemoryCandidate[], options: RerankOptions): MemoryCandidate[] {
   const { limit, now = new Date() } = options;
 
-  const scored = candidates.map((candidate) => ({
-    ...candidate,
-    similarity: computeScore(candidate, now),
-  }));
+  const scored = candidates.map((candidate) => {
+    const rawSimilarity = candidate.similarity;
+    const compositeScore = computeScore(candidate, now);
+    return {
+      ...candidate,
+      rawSimilarity,
+      compositeScore,
+      similarity: compositeScore,
+    };
+  });
 
   scored.sort((a, b) => b.similarity - a.similarity);
   return scored.slice(0, limit);

package/src/be/memory/types.ts

@@ -22,6 +22,10 @@ export interface MemoryStore {
   peek(id: string): AgentMemory | null;
   search(embedding: Float32Array, agentId: string, options: MemorySearchOptions): MemoryCandidate[];
   list(agentId: string, options: MemoryListOptions): AgentMemory[];
+  isSourceProtected(source: AgentMemorySource): boolean;
+  listForCuration(
+    agentId?: string,
+  ): { id: string; source: string; name: string; createdAt: string }[];
   listForReembedding(options?: { agentId?: string }): { id: string; content: string }[];
   delete(id: string): boolean;
   deleteBySourcePath(sourcePath: string, agentId: string): number;
@@ -51,6 +55,10 @@ export interface MemoryInput {
 
 export interface MemoryCandidate extends AgentMemory {
   similarity: number;
+  /** Raw cosine similarity before reranking (preserved for diagnostics). */
+  rawSimilarity?: number;
+  /** Final composite score after reranking (recency × source × usefulness × access). */
+  compositeScore?: number;
   accessCount: number;
   expiresAt: string | null;
   embeddingModel: string | null;