@desplega.ai/agent-swarm 1.73.1 → 1.73.3

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.73.1",
+    "version": "1.73.3",
     "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": [
@@ -2914,6 +2914,112 @@
         }
       }
     },
+    "/api/memory/list": {
+      "post": {
+        "summary": "List or semantically search memories across all agents (debug/admin)",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "query": {
+                    "type": "string",
+                    "description": "Natural-language query. If present, runs semantic search; otherwise lists by recency."
+                  },
+                  "agentId": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "Filter to a single agent. Omit for all."
+                  },
+                  "scope": {
+                    "type": "string",
+                    "enum": [
+                      "agent",
+                      "swarm",
+                      "all"
+                    ],
+                    "default": "all"
+                  },
+                  "source": {
+                    "type": "string",
+                    "enum": [
+                      "manual",
+                      "file_index",
+                      "session_summary",
+                      "task_completion"
+                    ]
+                  },
+                  "sourcePath": {
+                    "type": "string",
+                    "description": "Substring match against sourcePath (case-insensitive). Useful for file_index memories."
+                  },
+                  "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 20
+                  },
+                  "offset": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "default": 0
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Memory list / search results"
+          },
+          "400": {
+            "description": "Validation error"
+          }
+        }
+      }
+    },
+    "/api/memory/{id}": {
+      "delete": {
+        "summary": "Delete a single memory by ID (debug/admin)",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Memory deleted"
+          },
+          "404": {
+            "description": "Memory not found"
+          }
+        }
+      }
+    },
     "/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.73.1",
+  "version": "1.73.3",
   "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/http/memory.ts

@@ -69,6 +69,52 @@ const reEmbedMemory = route({
   },
 });
 
+const listMemory = route({
+  method: "post",
+  path: "/api/memory/list",
+  pattern: ["api", "memory", "list"],
+  summary: "List or semantically search memories across all agents (debug/admin)",
+  tags: ["Memory"],
+  auth: { apiKey: true },
+  body: z.object({
+    query: z
+      .string()
+      .optional()
+      .describe(
+        "Natural-language query. If present, runs semantic search; otherwise lists by recency.",
+      ),
+    agentId: z.string().uuid().optional().describe("Filter to a single agent. Omit for all."),
+    scope: z.enum(["agent", "swarm", "all"]).default("all"),
+    source: AgentMemorySourceSchema.optional(),
+    sourcePath: z
+      .string()
+      .optional()
+      .describe(
+        "Substring match against sourcePath (case-insensitive). Useful for file_index memories.",
+      ),
+    limit: z.number().int().min(1).max(100).default(20),
+    offset: z.number().int().min(0).default(0),
+  }),
+  responses: {
+    200: { description: "Memory list / search results" },
+    400: { description: "Validation error" },
+  },
+});
+
+const deleteMemoryById = route({
+  method: "delete",
+  path: "/api/memory/{id}",
+  pattern: ["api", "memory", null],
+  summary: "Delete a single memory by ID (debug/admin)",
+  tags: ["Memory"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string().uuid() }),
+  responses: {
+    200: { description: "Memory deleted" },
+    404: { description: "Memory not found" },
+  },
+});
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleMemory(
@@ -182,6 +228,132 @@ export async function handleMemory(
     return true;
   }
 
+  if (listMemory.match(req.method, pathSegments)) {
+    const parsed = await listMemory.parse(req, res, pathSegments, new URLSearchParams());
+    if (!parsed) return true;
+
+    const { query, agentId, scope, source, sourcePath, limit, offset } = parsed.body;
+    const store = getMemoryStore();
+    const pathNeedle = sourcePath?.trim().toLowerCase();
+    const matchesPath = (p: string | null) =>
+      !pathNeedle || (p?.toLowerCase().includes(pathNeedle) ?? false);
+
+    try {
+      if (query && query.trim().length > 0) {
+        const provider = getEmbeddingProvider();
+        const queryEmbedding = await provider.embed(query.trim());
+
+        if (!queryEmbedding) {
+          json(res, { results: [], total: 0, mode: "semantic" });
+          return true;
+        }
+
+        const candidateLimit = Math.min(limit, 100) * CANDIDATE_SET_MULTIPLIER;
+        let candidates = store.search(queryEmbedding, agentId ?? "", {
+          scope,
+          limit: candidateLimit,
+          isLead: true,
+          source,
+        });
+        if (agentId) {
+          candidates = candidates.filter((c) => c.agentId === agentId);
+        }
+        if (pathNeedle) {
+          candidates = candidates.filter((c) => matchesPath(c.sourcePath));
+        }
+        const ranked = rerank(candidates, { limit: Math.min(limit, 100) });
+
+        json(res, {
+          results: ranked.map((r) => ({
+            id: r.id,
+            name: r.name,
+            content: r.content,
+            agentId: r.agentId,
+            scope: r.scope,
+            source: r.source,
+            similarity: r.similarity,
+            createdAt: r.createdAt,
+            accessedAt: r.accessedAt,
+            accessCount: r.accessCount ?? 0,
+            expiresAt: r.expiresAt ?? null,
+            embeddingModel: r.embeddingModel ?? null,
+            sourceTaskId: r.sourceTaskId,
+            sourcePath: r.sourcePath,
+            chunkIndex: r.chunkIndex,
+            totalChunks: r.totalChunks,
+            tags: r.tags,
+          })),
+          total: ranked.length,
+          mode: "semantic",
+        });
+        return true;
+      }
+
+      // When filtering by sourcePath, over-fetch then post-filter so the visible
+      // page isn't gutted by the in-memory filter.
+      const fetchLimit = pathNeedle
+        ? Math.min(500, Math.max(limit * 10, 100))
+        : Math.min(limit, 100);
+      let rows = store.list(agentId ?? "", {
+        scope,
+        limit: fetchLimit,
+        offset,
+        isLead: true,
+      });
+      if (agentId) {
+        rows = rows.filter((r) => r.agentId === agentId);
+      }
+      if (source) {
+        rows = rows.filter((r) => r.source === source);
+      }
+      if (pathNeedle) {
+        rows = rows.filter((r) => matchesPath(r.sourcePath));
+      }
+      rows = rows.slice(0, Math.min(limit, 100));
+
+      json(res, {
+        results: rows.map((r) => ({
+          id: r.id,
+          name: r.name,
+          content: r.content,
+          agentId: r.agentId,
+          scope: r.scope,
+          source: r.source,
+          createdAt: r.createdAt,
+          accessedAt: r.accessedAt,
+          accessCount: r.accessCount ?? 0,
+          expiresAt: r.expiresAt ?? null,
+          embeddingModel: r.embeddingModel ?? null,
+          sourceTaskId: r.sourceTaskId,
+          sourcePath: r.sourcePath,
+          chunkIndex: r.chunkIndex,
+          totalChunks: r.totalChunks,
+          tags: r.tags,
+        })),
+        total: rows.length,
+        mode: "list",
+      });
+    } catch (err) {
+      console.error("[memory-list] Error:", (err as Error).message);
+      jsonError(res, "Memory list failed", 500);
+    }
+    return true;
+  }
+
+  if (deleteMemoryById.match(req.method, pathSegments)) {
+    const parsed = await deleteMemoryById.parse(req, res, pathSegments, new URLSearchParams());
+    if (!parsed) return true;
+
+    const store = getMemoryStore();
+    const deleted = store.delete(parsed.params.id);
+    if (!deleted) {
+      jsonError(res, "Memory not found", 404);
+      return true;
+    }
+    json(res, { deleted: true });
+    return true;
+  }
+
   if (reEmbedMemory.match(req.method, pathSegments)) {
     const parsed = await reEmbedMemory.parse(req, res, pathSegments, new URLSearchParams());
     if (!parsed) return true;

package/src/oauth/ensure-token.ts

@@ -26,11 +26,35 @@ function getOAuthConfig(provider: string): OAuthProviderConfig | null {
  * If the token is expiring soon, attempt to refresh it.
  * Call this before any API interaction with an OAuth-protected service.
  *
+ * Reactive variant — never throws. Refresh failures are logged so a single
+ * dead-token incident doesn't tear down an unrelated request path. Use
+ * {@link ensureTokenOrThrow} from keepalive contexts where you want a dead
+ * refresh token to surface as an alert.
+ *
  * @param bufferMs - How far ahead to check for expiry. Default 5 min (reactive use).
  *                   Keepalive callers should pass a larger value (e.g. 13h) to force
  *                   a proactive refresh well before the token actually expires.
  */
 export async function ensureToken(provider: string, bufferMs?: number): Promise<void> {
+  try {
+    await ensureTokenOrThrow(provider, bufferMs);
+  } catch (err) {
+    console.error(
+      `[OAuth] Failed to refresh ${provider} token:`,
+      err instanceof Error ? err.message : err,
+    );
+  }
+}
+
+/**
+ * Strict variant of {@link ensureToken}: throws on refresh failure of a
+ * configured provider so callers (keepalive, alerting) can react.
+ *
+ * Stays silent (no throw) when the provider isn't configured or no refresh
+ * token is stored — those are "not connected" states, not failures, and
+ * shouldn't page anyone.
+ */
+export async function ensureTokenOrThrow(provider: string, bufferMs?: number): Promise<void> {
   if (!isTokenExpiringSoon(provider, bufferMs)) return;
 
   const config = getOAuthConfig(provider);
@@ -42,13 +66,6 @@ export async function ensureToken(provider: string, bufferMs?: number): Promise<
     return;
   }
 
-  try {
-    await refreshAccessToken(config, tokens.refreshToken);
-    console.log(`[OAuth] ${provider} token refreshed successfully`);
-  } catch (err) {
-    console.error(
-      `[OAuth] Failed to refresh ${provider} token:`,
-      err instanceof Error ? err.message : err,
-    );
-  }
+  await refreshAccessToken(config, tokens.refreshToken);
+  console.log(`[OAuth] ${provider} token refreshed successfully`);
 }

package/src/oauth/keepalive.ts

@@ -1,26 +1,36 @@
-import { ensureToken } from "./ensure-token";
+import { ensureTokenOrThrow } from "./ensure-token";
 
 const TWELVE_HOURS_MS = 12 * 60 * 60 * 1000;
 const THIRTEEN_HOURS_MS = 13 * 60 * 60 * 1000;
 const SLACK_ALERTS_CHANNEL = process.env.SLACK_ALERTS_CHANNEL || "C08JCRURPBV";
 
+const KEEPALIVE_PROVIDERS = ["linear", "jira"] as const;
+
 let keepaliveInterval: ReturnType<typeof setInterval> | null = null;
 
 /**
  * Proactively refresh OAuth tokens on a schedule to prevent expiry.
  * If refresh fails, posts a Slack notification so someone can re-auth manually.
+ *
+ * Why both Linear and Jira: Atlassian rotates refresh tokens and expires them
+ * after 90 days of inactivity, so a swarm that doesn't touch Jira for a long
+ * stretch will silently lose the ability to refresh. Touching the token every
+ * 12h keeps the refresh token alive and surfaces a dead one as an alert
+ * instead of a runtime 401.
  */
 async function runKeepalive(): Promise<void> {
-  console.log("[OAuth Keepalive] Running scheduled token refresh for linear...");
-  try {
-    await ensureToken("linear", THIRTEEN_HOURS_MS);
-    console.log("[OAuth Keepalive] linear token check completed successfully");
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`[OAuth Keepalive] Failed to refresh linear token: ${message}`);
-    await notifySlack(
-      `⚠️ *OAuth Keepalive Failed*\nProvider: \`linear\`\nError: ${message}\n\nManual re-authorization may be required.`,
-    );
+  for (const provider of KEEPALIVE_PROVIDERS) {
+    console.log(`[OAuth Keepalive] Running scheduled token refresh for ${provider}...`);
+    try {
+      await ensureTokenOrThrow(provider, THIRTEEN_HOURS_MS);
+      console.log(`[OAuth Keepalive] ${provider} token check completed successfully`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[OAuth Keepalive] Failed to refresh ${provider} token: ${message}`);
+      await notifySlack(
+        `⚠️ *OAuth Keepalive Failed*\nProvider: \`${provider}\`\nError: ${message}\n\nManual re-authorization may be required.`,
+      );
+    }
   }
 }
 

package/src/tests/ensure-token.test.ts

@@ -7,7 +7,7 @@ import {
   storeOAuthTokens,
   upsertOAuthApp,
 } from "../be/db-queries/oauth";
-import { ensureToken } from "../oauth/ensure-token";
+import { ensureToken, ensureTokenOrThrow } from "../oauth/ensure-token";
 
 const TEST_DB_PATH = "./test-ensure-token.sqlite";
 
@@ -202,3 +202,35 @@ describe("ensureToken", () => {
     expect(fetchSpy).not.toHaveBeenCalled();
   });
 });
+
+describe("ensureTokenOrThrow", () => {
+  test("throws when refresh fails for a configured provider (so keepalive can alert)", async () => {
+    storeOAuthTokens("test-provider", {
+      accessToken: "old-token",
+      refreshToken: "refresh-token",
+      expiresAt: new Date(Date.now() + 60 * 1000).toISOString(),
+    });
+
+    globalThis.fetch = mock(() =>
+      Promise.resolve(
+        new Response('{"error":"invalid_grant"}', {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }),
+      ),
+    );
+
+    await expect(ensureTokenOrThrow("test-provider")).rejects.toThrow(/Token refresh failed/);
+  });
+
+  test("stays silent (no throw) when no refresh token is stored", async () => {
+    deleteOAuthTokens("test-provider");
+
+    // "Not connected" should not page anyone
+    await expect(ensureTokenOrThrow("test-provider")).resolves.toBeUndefined();
+  });
+
+  test("stays silent (no throw) when provider is not configured", async () => {
+    await expect(ensureTokenOrThrow("nonexistent-provider")).resolves.toBeUndefined();
+  });
+});