@desplega.ai/agent-swarm 1.74.3 → 1.75.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.74.3",
+    "version": "1.75.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": [
@@ -621,6 +621,126 @@
         }
       }
     },
+    "/api/agents/{id}/credential-status": {
+      "put": {
+        "summary": "Worker self-report of credential readiness (Phase 3 boot loop)",
+        "tags": [
+          "Agents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "ready": {
+                    "type": "boolean"
+                  },
+                  "missing": {
+                    "type": [
+                      "array",
+                      "null"
+                    ],
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "required": [
+                  "ready"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "State updated; returns the agent row."
+          },
+          "404": {
+            "description": "Agent not found"
+          }
+        }
+      },
+      "get": {
+        "summary": "Single-agent credential-status snapshot for the dashboard",
+        "tags": [
+          "Agents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Credential status payload"
+          },
+          "404": {
+            "description": "Agent not found"
+          }
+        }
+      }
+    },
+    "/api/agents/credential-status": {
+      "get": {
+        "summary": "Bulk credential-status across all agents (powers the dashboard)",
+        "tags": [
+          "Agents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "idle",
+                "busy",
+                "offline",
+                "waiting_for_credentials"
+              ]
+            },
+            "required": false,
+            "name": "status",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of {agentId, status, missing[], lastCheckedAt}"
+          }
+        }
+      }
+    },
     "/api/approval-requests": {
       "post": {
         "summary": "Create a new approval request",
@@ -3031,6 +3151,167 @@
         }
       }
     },
+    "/api/memory/rate": {
+      "post": {
+        "summary": "Submit RatingEvents to update memory usefulness posteriors",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "events": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "memoryId": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "signal": {
+                          "type": "number",
+                          "minimum": -1,
+                          "maximum": 1
+                        },
+                        "weight": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1
+                        },
+                        "source": {
+                          "type": "string",
+                          "enum": [
+                            "llm",
+                            "explicit-self"
+                          ]
+                        },
+                        "reasoning": {
+                          "type": "string",
+                          "maxLength": 500
+                        },
+                        "taskId": {
+                          "type": "string",
+                          "format": "uuid"
+                        },
+                        "referencesSource": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 512,
+                          "description": "Optional external source ID this memory references. Free-form string, convention \"<source>:<identifier>\" (e.g. \"github:owner/repo#N\", \"linear:KEY-N\", \"customer:<slug>\", \"slack:<channel>:<ts>\", \"agentmail:<thread-id>\"). Pick any prefix that fits — no closed enum. When present, an edge from this memory to the external source is created/updated."
+                        }
+                      },
+                      "required": [
+                        "memoryId",
+                        "signal",
+                        "weight",
+                        "source"
+                      ]
+                    },
+                    "minItems": 1,
+                    "maxItems": 50
+                  }
+                },
+                "required": [
+                  "events"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Ratings applied; per-event rejections returned in body"
+          },
+          "400": {
+            "description": "Validation error or explicit-self R6 spam-guard rejection"
+          },
+          "409": {
+            "description": "Duplicate explicit-self rating for (taskId, memoryId)"
+          }
+        }
+      }
+    },
+    "/api/memory/retrievals": {
+      "get": {
+        "summary": "List memories retrieved for a task or session (rater input)",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "required": false,
+            "name": "taskId",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "sessionId",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Retrieval rows joined with agent_memory"
+          },
+          "400": {
+            "description": "Missing taskId/sessionId or X-Agent-ID"
+          }
+        }
+      }
+    },
+    "/api/memory/edges": {
+      "get": {
+        "summary": "List references-source edges for a memory",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": true,
+            "name": "memoryId",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Edges with computed usefulness scores"
+          },
+          "400": {
+            "description": "Missing memoryId or X-Agent-ID"
+          }
+        }
+      }
+    },
     "/api/prompt-templates/resolved": {
       "get": {
         "summary": "Resolve a prompt template for a given event type and scope chain",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.74.3",
+  "version": "1.75.0",
   "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

@@ -555,6 +555,8 @@ type AgentRow = {
   provider: string | null;
   createdAt: string;
   lastUpdatedAt: string;
+  /** JSON array of env-var names; populated only when status is `waiting_for_credentials`. */
+  credentialMissing: string | null;
 };
 
 function rowToAgent(row: AgentRow): Agent {
@@ -578,6 +580,9 @@ function rowToAgent(row: AgentRow): Agent {
     provider: (row.provider as ProviderName | null) ?? undefined,
     createdAt: row.createdAt,
     lastUpdatedAt: row.lastUpdatedAt,
+    credentialMissing: row.credentialMissing
+      ? (JSON.parse(row.credentialMissing) as string[])
+      : null,
   };
 }
 
@@ -596,9 +601,36 @@ export const agentQueries = {
       "UPDATE agents SET status = ?, lastUpdatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = ? RETURNING *",
     ),
 
+  updateCredentialState: () =>
+    getDb().prepare<AgentRow, [AgentStatus, string | null, string]>(
+      "UPDATE agents SET status = ?, credentialMissing = ?, lastUpdatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = ? RETURNING *",
+    ),
+
   delete: () => getDb().prepare<null, [string]>("DELETE FROM agents WHERE id = ?"),
 };
 
+/**
+ * Phase 3 of the worker credential safe-loop plan.
+ *
+ * `ready=true` clears the waiting state — the agent transitions to `idle`
+ * and the dispatcher will start handing it tasks again.
+ *
+ * `ready=false` parks the agent on `waiting_for_credentials` with the env-var
+ * names it's blocked on. The capacity dispatch query already filters
+ * `status === 'idle'` so the new value is implicitly excluded with no other
+ * code change.
+ */
+export function updateAgentCredentialState(
+  agentId: string,
+  ready: boolean,
+  missing: string[] | null,
+): Agent | null {
+  const status: AgentStatus = ready ? "idle" : "waiting_for_credentials";
+  const missingJson = ready ? null : missing && missing.length > 0 ? JSON.stringify(missing) : null;
+  const row = agentQueries.updateCredentialState().get(status, missingJson, agentId);
+  return row ? rowToAgent(row) : null;
+}
+
 export function createAgent(
   agent: Omit<Agent, "id" | "createdAt" | "lastUpdatedAt"> & { id?: string },
 ): Agent {
@@ -774,6 +806,10 @@ export function getRemainingCapacity(agentId: string): number {
 export function updateAgentStatusFromCapacity(agentId: string): void {
   const agent = getAgentById(agentId);
   if (!agent || agent.status === "offline") return;
+  // `waiting_for_credentials` is owned by the worker's credential-wait
+  // tick — task-completion shouldn't accidentally promote a blocked agent
+  // back to idle.
+  if (agent.status === "waiting_for_credentials") return;
 
   const activeCount = getActiveTaskCount(agentId);
   const newStatus = activeCount > 0 ? "busy" : "idle";

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;
+  }
+}