@desplega.ai/agent-swarm 1.92.1 → 1.93.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.92.1",
+    "version": "1.93.0",
     "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": [
@@ -2740,6 +2740,59 @@
         }
       }
     },
+    "/api/keys/clear-rate-limit": {
+      "post": {
+        "summary": "Clear rate-limited status for a key after a successful use proves it is healthy",
+        "tags": [
+          "API Keys"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keyType": {
+                    "type": "string"
+                  },
+                  "keySuffix": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 10
+                  },
+                  "scope": {
+                    "type": "string"
+                  },
+                  "scopeId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "keyType",
+                  "keySuffix"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Rate limit cleared (or key was not rate-limited)"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/events": {
       "post": {
         "summary": "Store a single event",
@@ -10711,9 +10764,9 @@
         }
       }
     },
-    "/api/tasks/{id}/claude-session": {
+    "/api/tasks/{id}/session": {
       "put": {
-        "summary": "Update Claude session ID for a task",
+        "summary": "Update provider session ID and harness metadata for a task",
         "tags": [
           "Tasks"
         ],
@@ -10800,6 +10853,13 @@
                       "providerMeta": {
                         "type": "object",
                         "properties": {}
+                      },
+                      "harnessVariant": {
+                        "type": "string"
+                      },
+                      "harnessVariantMeta": {
+                        "type": "object",
+                        "additionalProperties": {}
                       }
                     },
                     "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.92.1",
+  "version": "1.93.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -112,11 +112,11 @@
     "@desplega.ai/localtunnel": "^2.2.0",
     "@inkjs/ui": "^2.0.0",
     "@linear/sdk": "^77.0.0",
-    "@earendil-works/pi-agent-core": "^0.78.1",
-    "@earendil-works/pi-ai": "^0.78.1",
-    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-agent-core": "^0.79.1",
+    "@earendil-works/pi-ai": "^0.79.1",
+    "@earendil-works/pi-coding-agent": "^0.79.1",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@openai/codex-sdk": "^0.137.0",
+    "@openai/codex-sdk": "^0.139.0",
     "@opencode-ai/sdk": "^1.16.2",
     "@openfort/openfort-node": "^0.9.1",
     "@opentelemetry/api": "^1.9.1",

package/src/be/db.ts

@@ -65,6 +65,7 @@ import type {
   ScriptRun,
   ScriptRunJournalEntry,
   ScriptRunKind,
+  ScriptRunListItem,
   ScriptRunStatus,
   Service,
   ServiceStatus,
@@ -1041,6 +1042,8 @@ type AgentTaskRow = {
   swarmVersion: string | null;
   provider: string | null;
   providerMeta: string | null;
+  harnessVariant: string | null;
+  harnessVariantMeta: string | null;
   totalCostUsd?: number | null;
 };
 
@@ -1102,7 +1105,7 @@ function rowToAgentTask(row: AgentTaskRow): AgentTask {
     dir: row.dir ?? undefined,
     parentTaskId: row.parentTaskId ?? undefined,
     claudeSessionId: row.claudeSessionId ?? undefined,
-    model: (row.model as "haiku" | "sonnet" | "opus" | null) ?? undefined,
+    model: (row.model as "haiku" | "sonnet" | "opus" | "fable" | null) ?? undefined,
     scheduleId: row.scheduleId ?? undefined,
     workflowRunId: row.workflowRunId ?? undefined,
     workflowRunStepId: row.workflowRunStepId ?? undefined,
@@ -1127,6 +1130,8 @@ function rowToAgentTask(row: AgentTaskRow): AgentTask {
     swarmVersion: row.swarmVersion ?? undefined,
     provider: (row.provider as ProviderName | null) ?? undefined,
     providerMeta: parseProviderMeta(row.provider as ProviderName | null, row.providerMeta),
+    harnessVariant: row.harnessVariant ?? undefined,
+    harnessVariantMeta: row.harnessVariantMeta ? JSON.parse(row.harnessVariantMeta) : undefined,
     totalCostUsd: row.totalCostUsd ?? undefined,
   };
 }
@@ -1398,6 +1403,8 @@ export function updateTaskClaudeSessionId(
   provider?: ProviderName,
   providerMeta?: Record<string, unknown>,
   model?: string,
+  harnessVariant?: string,
+  harnessVariantMeta?: Record<string, unknown>,
 ): AgentTask | null {
   const setClauses = ["claudeSessionId = ?", "lastUpdatedAt = ?"];
   const params: (string | null)[] = [claudeSessionId, new Date().toISOString()];
@@ -1414,6 +1421,14 @@ export function updateTaskClaudeSessionId(
     setClauses.push("model = ?");
     params.push(model);
   }
+  if (harnessVariant !== undefined) {
+    setClauses.push("harnessVariant = ?");
+    params.push(harnessVariant);
+  }
+  if (harnessVariantMeta !== undefined) {
+    setClauses.push("harnessVariantMeta = ?");
+    params.push(JSON.stringify(harnessVariantMeta));
+  }
 
   params.push(taskId);
 
@@ -2117,6 +2132,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 +2178,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 +2247,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 +3425,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
 // ============================================================================
@@ -5202,7 +5306,7 @@ function rowToScheduledTask(row: ScheduledTaskRow): ScheduledTask {
     consecutiveErrors: row.consecutiveErrors ?? 0,
     lastErrorAt: normalizeDate(row.lastErrorAt) ?? undefined,
     lastErrorMessage: row.lastErrorMessage ?? undefined,
-    model: (row.model as "haiku" | "sonnet" | "opus" | null) ?? undefined,
+    model: (row.model as "haiku" | "sonnet" | "opus" | "fable" | null) ?? undefined,
     scheduleType: row.scheduleType as "recurring" | "one_time",
     createdAt: normalizeDateRequired(row.createdAt),
     lastUpdatedAt: normalizeDateRequired(row.lastUpdatedAt),
@@ -9969,6 +10073,28 @@ export function setApiKeyName(
   return result.changes > 0;
 }
 
+/**
+ * Clear a stale rate-limit record after a successful use proves the key is healthy.
+ */
+export function clearKeyRateLimit(
+  keyType: string,
+  keySuffix: string,
+  scope = "global",
+  scopeId: string | null = null,
+): boolean {
+  const now = new Date().toISOString();
+  const effectiveScopeId = scopeId ?? "";
+  const result = getDb()
+    .prepare(
+      `UPDATE api_key_status
+       SET status = 'available', rateLimitedUntil = NULL, updatedAt = ?
+       WHERE keyType = ? AND keySuffix = ? AND scope = ? AND scopeId = ?
+         AND status = 'rate_limited'`,
+    )
+    .run(now, keyType, keySuffix, scope, effectiveScopeId);
+  return result.changes > 0;
+}
+
 /**
  * Get all key status records for a credential type.
  */
@@ -11485,6 +11611,22 @@ type ScriptRunRow = {
   updated_by: string | null;
 };
 
+type ScriptRunListRow = Pick<
+  ScriptRunRow,
+  | "id"
+  | "agentId"
+  | "scriptName"
+  | "kind"
+  | "status"
+  | "pid"
+  | "startedAt"
+  | "finishedAt"
+  | "error"
+  | "last_heartbeat_at"
+  | "idempotencyKey"
+  | "requestedByUserId"
+>;
+
 function parseJsonColumn(value: string | null): unknown | undefined {
   if (value === null) return undefined;
   return JSON.parse(value);
@@ -11510,6 +11652,23 @@ function rowToScriptRun(row: ScriptRunRow): ScriptRun {
   };
 }
 
+function rowToScriptRunListItem(row: ScriptRunListRow): ScriptRunListItem {
+  return {
+    id: row.id,
+    agentId: row.agentId,
+    scriptName: row.scriptName ?? undefined,
+    kind: row.kind as ScriptRunKind,
+    status: row.status as ScriptRunStatus,
+    pid: row.pid ?? undefined,
+    startedAt: row.startedAt,
+    finishedAt: row.finishedAt ?? undefined,
+    error: row.error ?? undefined,
+    lastHeartbeatAt: row.last_heartbeat_at ?? undefined,
+    idempotencyKey: row.idempotencyKey ?? undefined,
+    requestedByUserId: row.requestedByUserId ?? undefined,
+  };
+}
+
 export function createScriptRun(data: {
   id: string;
   agentId: string;
@@ -11644,7 +11803,7 @@ export function listScriptRuns(opts?: {
   agentId?: string;
   limit?: number;
   offset?: number;
-}): ScriptRun[] {
+}): ScriptRunListItem[] {
   const conditions: string[] = [];
   const params: Array<string | number> = [];
   if (opts?.status) {
@@ -11661,11 +11820,26 @@ export function listScriptRuns(opts?: {
   params.push(limit, offset);
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const rows = getDb()
-    .prepare<ScriptRunRow, Array<string | number>>(
-      `SELECT * FROM script_runs ${where} ORDER BY startedAt DESC LIMIT ? OFFSET ?`,
+    .prepare<ScriptRunListRow, Array<string | number>>(
+      `SELECT
+        id,
+        agentId,
+        scriptName,
+        kind,
+        status,
+        pid,
+        startedAt,
+        finishedAt,
+        error,
+        last_heartbeat_at,
+        idempotencyKey,
+        requestedByUserId
+       FROM script_runs ${where}
+       ORDER BY startedAt DESC
+       LIMIT ? OFFSET ?`,
     )
     .all(...params);
-  return rows.map(rowToScriptRun);
+  return rows.map(rowToScriptRunListItem);
 }
 
 export function countScriptRuns(opts?: { status?: ScriptRunStatus; agentId?: string }): number {

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

@@ -0,0 +1,84 @@
+/**
+ * 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;
+
+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);
         }
       }