@desplega.ai/agent-swarm 1.123.0 → 1.124.0

package/src/tools/memory-delete.ts

@@ -3,7 +3,7 @@ import * as z from "zod";
 import { getAgentById } from "@/be/db";
 import { getMemoryStore } from "@/be/memory";
 import { can } from "@/rbac";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerMemoryDeleteTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -17,36 +17,22 @@ export const registerMemoryDeleteTool = (server: McpServer) => {
       inputSchema: z.object({
         memoryId: z.uuid().describe("The ID of the memory to delete."),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
       }),
     },
     async ({ memoryId }, requestInfo, _meta) => {
       if (!requestInfo.agentId) {
-        return {
-          content: [{ type: "text", text: "Agent ID required to delete memories." }],
-          structuredContent: {
-            yourAgentId: undefined,
-            success: false,
-            message: "Agent ID required. Are you registered in the swarm?",
-          },
-        };
+        return toolErr("Agent ID required. Are you registered in the swarm?");
       }
 
       const store = getMemoryStore();
       const memory = store.peek(memoryId);
 
       if (!memory) {
-        return {
-          content: [{ type: "text", text: `Memory "${memoryId}" not found.` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: `Memory "${memoryId}" not found.`,
-          },
-        };
+        return toolErr(`Memory "${memoryId}" not found.`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
 
       // Permission check: own memories or lead can delete swarm-scoped
@@ -62,36 +48,20 @@ export const registerMemoryDeleteTool = (server: McpServer) => {
         source: "mcp",
       });
       if (!decision.allow) {
-        return {
-          content: [{ type: "text", text: "You don't have permission to delete this memory." }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message:
-              "Permission denied. You can only delete your own memories, or swarm memories if you are the lead.",
-          },
-        };
+        return toolErr(
+          "Permission denied. You can only delete your own memories, or swarm memories if you are the lead.",
+          { data: { yourAgentId: requestInfo.agentId } },
+        );
       }
 
       const deleted = store.delete(memoryId);
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: deleted
-              ? `Memory "${memoryId}" deleted.`
-              : `Failed to delete memory "${memoryId}".`,
-          },
-        ],
-        structuredContent: {
-          yourAgentId: requestInfo.agentId,
-          success: deleted,
-          message: deleted
-            ? `Memory "${memoryId}" deleted.`
-            : `Failed to delete memory "${memoryId}".`,
-        },
-      };
+      const message = deleted
+        ? `Memory "${memoryId}" deleted.`
+        : `Failed to delete memory "${memoryId}".`;
+      return deleted
+        ? toolOk(message, { data: { yourAgentId: requestInfo.agentId } })
+        : toolErr(message, { data: { yourAgentId: requestInfo.agentId } });
     },
   );
 };

package/src/tools/memory-edit.ts

@@ -2,8 +2,33 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getEmbeddingProvider, getMemoryStore } from "@/be/memory";
 import { refreshLinks } from "@/be/memory/link-resolver";
-import { createToolRegistrar } from "@/tools/utils";
-import { AgentMemorySchema, AgentMemoryScopeSchema } from "@/types";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+import { AgentMemoryScopeSchema, AgentMemorySourceSchema } from "@/types";
+
+// Loose, format-pin-free mirror of AgentMemorySchema for MCP output validation.
+const agentMemoryOutputSchema = z.looseObject({
+  id: z.string().optional(),
+  agentId: z.string().nullable().optional(),
+  scope: AgentMemoryScopeSchema.optional(),
+  key: z.string().nullable().optional(),
+  name: z.string().optional(),
+  content: z.string().optional(),
+  summary: z.string().nullable().optional(),
+  source: AgentMemorySourceSchema.optional(),
+  sourceTaskId: z.string().nullable().optional(),
+  sourcePath: z.string().nullable().optional(),
+  chunkIndex: z.number().int().optional(),
+  totalChunks: z.number().int().optional(),
+  tags: z.array(z.string()).optional(),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().nullable().optional(),
+  accessedAt: z.string().optional(),
+  expiresAt: z.string().nullable().optional(),
+  accessCount: z.number().int().optional(),
+  embeddingModel: z.string().nullable().optional(),
+  contentHash: z.string().nullable().optional(),
+  version: z.number().int().optional(),
+});
 
 export const registerMemoryEditTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -45,11 +70,9 @@ export const registerMemoryEditTool = (server: McpServer) => {
         intent: z.string().min(1).describe("Why you are editing this memory."),
         expectedVersion: z.number().int().min(1).optional(),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        memory: AgentMemorySchema.optional(),
+        memory: agentMemoryOutputSchema.optional(),
         changed: z.boolean().optional(),
         previousVersion: z.number().int().optional(),
         version: z.number().int().optional(),
@@ -61,25 +84,13 @@ export const registerMemoryEditTool = (server: McpServer) => {
       _meta,
     ) => {
       if (!requestInfo.agentId) {
-        return {
-          content: [{ type: "text", text: "Agent ID required to edit memories." }],
-          structuredContent: {
-            yourAgentId: undefined,
-            success: false,
-            message: "Agent ID required. Are you registered in the swarm?",
-          },
-        };
+        return toolErr("Agent ID required. Are you registered in the swarm?");
       }
 
       if (!memoryId && !(key && scope)) {
-        return {
-          content: [{ type: "text", text: "memoryId or key+scope required." }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "memoryId or key+scope required.",
-          },
-        };
+        return toolErr("memoryId or key+scope required.", {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
 
       try {
@@ -113,36 +124,24 @@ export const registerMemoryEditTool = (server: McpServer) => {
           }
         }
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: result.changed
-                ? `Memory "${result.memory.id}" edited to version ${result.version}.`
-                : `Memory "${result.memory.id}" unchanged.`,
+        return toolOk(
+          result.changed
+            ? `Memory "${result.memory.id}" edited to version ${result.version}.`
+            : `Memory "${result.memory.id}" unchanged.`,
+          {
+            data: {
+              yourAgentId: requestInfo.agentId,
+              memory: result.memory,
+              changed: result.changed,
+              previousVersion: result.previousVersion,
+              version: result.version,
             },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: result.changed
-              ? `Memory edited to version ${result.version}.`
-              : "Memory unchanged.",
-            memory: result.memory,
-            changed: result.changed,
-            previousVersion: result.previousVersion,
-            version: result.version,
           },
-        };
+        );
       } catch (err) {
-        return {
-          content: [{ type: "text", text: `Memory edit failed: ${(err as Error).message}` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: `Memory edit failed: ${(err as Error).message}`,
-          },
-        };
+        return toolErr(`Memory edit failed: ${(err as Error).message}`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
     },
   );

package/src/tools/memory-get.ts

@@ -5,19 +5,44 @@ import { getMemoryStore } from "@/be/memory";
 import { canReadMemory } from "@/be/memory/access";
 import { getLinksForMemory, type MemoryLinksResult } from "@/be/memory/links-store";
 import { recordRetrievals } from "@/be/memory/raters/retrieval";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import type { AgentMemorySource } from "@/types";
-import { AgentMemorySchema } from "@/types";
+import { AgentMemoryScopeSchema, AgentMemorySourceSchema } from "@/types";
 
 const NUDGE_ELIGIBLE_SOURCES: ReadonlySet<AgentMemorySource> = new Set(["manual", "file_index"]);
 
-const LinkedMemoryRefSchema = z.object({
+// Loose, format-pin-free mirror of AgentMemorySchema for MCP output validation.
+const agentMemoryOutputSchema = z.looseObject({
+  id: z.string().optional(),
+  agentId: z.string().nullable().optional(),
+  scope: AgentMemoryScopeSchema.optional(),
+  key: z.string().nullable().optional(),
+  name: z.string().optional(),
+  content: z.string().optional(),
+  summary: z.string().nullable().optional(),
+  source: AgentMemorySourceSchema.optional(),
+  sourceTaskId: z.string().nullable().optional(),
+  sourcePath: z.string().nullable().optional(),
+  chunkIndex: z.number().int().optional(),
+  totalChunks: z.number().int().optional(),
+  tags: z.array(z.string()).optional(),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().nullable().optional(),
+  accessedAt: z.string().optional(),
+  expiresAt: z.string().nullable().optional(),
+  accessCount: z.number().int().optional(),
+  embeddingModel: z.string().nullable().optional(),
+  contentHash: z.string().nullable().optional(),
+  version: z.number().int().optional(),
+});
+
+const LinkedMemoryRefSchema = z.looseObject({
   id: z.string(),
   name: z.string(),
   scope: z.string(),
 });
 
-const MemoryLinkSchema = z.object({
+const MemoryLinkSchema = z.looseObject({
   id: z.string(),
   linkType: z.string(),
   targetKind: z.string(),
@@ -36,7 +61,7 @@ const MemoryLinkSchema = z.object({
   ),
 });
 
-const MemoryBacklinkSchema = z.object({
+const MemoryBacklinkSchema = z.looseObject({
   id: z.string(),
   linkType: z.string(),
   strength: z.number(),
@@ -63,11 +88,9 @@ export const registerMemoryGetTool = (server: McpServer) => {
             "Why you are retrieving this memory. Required. E.g. 'need full details of the auth fix pattern'.",
           ),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        memory: AgentMemorySchema.optional(),
+        memory: agentMemoryOutputSchema.optional(),
         links: z
           .array(MemoryLinkSchema)
           .optional()
@@ -84,25 +107,13 @@ export const registerMemoryGetTool = (server: McpServer) => {
       const memoryForAuth = store.peek(memoryId);
 
       if (!memoryForAuth) {
-        return {
-          content: [{ type: "text", text: `Memory "${memoryId}" not found.` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: `Memory "${memoryId}" not found.`,
-          },
-        };
+        return toolErr(`Memory "${memoryId}" not found.`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
 
       if (!canReadMemory(memoryForAuth, requestInfo.agentId)) {
-        return {
-          content: [{ type: "text", text: "Not authorized" }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Not authorized",
-          },
-        };
+        return toolErr("Not authorized", { data: { yourAgentId: requestInfo.agentId } });
       }
 
       const memory = store.get(memoryId)!;
@@ -146,23 +157,16 @@ export const registerMemoryGetTool = (server: McpServer) => {
           ? `\n\n[${linkBlocks.links.length} outgoing link(s), ${linkBlocks.backlinks.length} backlink(s) — see structured output]`
           : "";
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Memory "${memory.name}" retrieved.\n\n${memory.content}${linksSummary}`,
-          },
-        ],
-        structuredContent: {
+      return toolOk(`Memory "${memory.name}" retrieved.`, {
+        details: `${memory.content}${linksSummary}`,
+        data: {
           yourAgentId: requestInfo.agentId,
-          success: true,
-          message: `Memory "${memory.name}" retrieved.`,
           memory,
           links: linkBlocks.links,
           backlinks: linkBlocks.backlinks,
           rateHint,
         },
-      };
+      });
     },
   );
 };

package/src/tools/memory-rate.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { REFERENCES_SOURCE_MAX_LENGTH, sanitizeReferencesSource } from "@/be/memory/raters/types";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import { getApiKey } from "@/utils/api-key";
 import { getMcpBaseUrl } from "@/utils/constants";
 
@@ -58,37 +58,25 @@ export const registerMemoryRateTool = (server: McpServer) => {
           .optional()
           .describe(REFERENCES_SOURCE_DESCRIPTION),
       }),
-      outputSchema: z.object({
-        success: z.boolean(),
-        message: z.string(),
-      }),
+      outputSchema: swarmToolOutputSchema(),
     },
     async ({ id, useful, note, referencesSource }, requestInfo, _meta) => {
       if (!requestInfo.agentId) {
-        const msg = "Agent ID required. Are you registered in the swarm?";
-        return {
-          content: [{ type: "text", text: msg }],
-          structuredContent: { success: false, message: msg },
-        };
+        return toolErr("Agent ID required. Are you registered in the swarm?");
       }
       if (!requestInfo.sourceTaskId) {
-        const msg = "memory_rate must be called from within a task — no source task ID was found.";
-        return {
-          content: [{ type: "text", text: msg }],
-          structuredContent: { success: false, message: msg },
-        };
+        return toolErr(
+          "memory_rate must be called from within a task — no source task ID was found.",
+        );
       }
 
       let cleanedReferencesSource: string | undefined;
       if (referencesSource !== undefined) {
         const cleaned = sanitizeReferencesSource(referencesSource);
         if (cleaned === null) {
-          const msg =
-            "referencesSource must not contain NUL bytes or strip to empty after control-char removal.";
-          return {
-            content: [{ type: "text", text: msg }],
-            structuredContent: { success: false, message: msg },
-          };
+          return toolErr(
+            "referencesSource must not contain NUL bytes or strip to empty after control-char removal.",
+          );
         }
         cleanedReferencesSource = cleaned;
       }
@@ -120,10 +108,7 @@ export const registerMemoryRateTool = (server: McpServer) => {
         });
 
         if (response.status === 409) {
-          return {
-            content: [{ type: "text", text: DUPLICATE_MESSAGE }],
-            structuredContent: { success: false, message: DUPLICATE_MESSAGE },
-          };
+          return toolErr(DUPLICATE_MESSAGE);
         }
 
         if (response.status === 400) {
@@ -137,31 +122,16 @@ export const registerMemoryRateTool = (server: McpServer) => {
           const msg = serverError
             ? `Memory rating rejected: ${serverError}. The memory must have been retrieved by this task before it can be rated.`
             : "Memory rating rejected. The memory must have been retrieved by this task before it can be rated.";
-          return {
-            content: [{ type: "text", text: msg }],
-            structuredContent: { success: false, message: msg },
-          };
+          return toolErr(msg);
         }
 
         if (!response.ok) {
-          const msg = `Memory rating failed (HTTP ${response.status}).`;
-          return {
-            content: [{ type: "text", text: msg }],
-            structuredContent: { success: false, message: msg },
-          };
+          return toolErr(`Memory rating failed (HTTP ${response.status}).`);
         }
 
-        const successMsg = `Memory ${id} rated as ${useful ? "useful" : "not useful"}.`;
-        return {
-          content: [{ type: "text", text: successMsg }],
-          structuredContent: { success: true, message: successMsg },
-        };
+        return toolOk(`Memory ${id} rated as ${useful ? "useful" : "not useful"}.`);
       } catch (err) {
-        const msg = `Memory rating failed: ${(err as Error).message}`;
-        return {
-          content: [{ type: "text", text: msg }],
-          structuredContent: { success: false, message: msg },
-        };
+        return toolErr(`Memory rating failed: ${(err as Error).message}`);
       }
     },
   );

package/src/tools/memory-search.ts

@@ -6,7 +6,7 @@ import { CANDIDATE_SET_MULTIPLIER } from "@/be/memory/constants";
 import { expandCandidatesWithGraph } from "@/be/memory/graph-expansion";
 import { recordRetrievals } from "@/be/memory/raters/retrieval";
 import { rerank } from "@/be/memory/reranker";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import type { AgentMemorySource } from "@/types";
 import { AgentMemoryScopeSchema, AgentMemorySourceSchema } from "@/types";
 
@@ -16,30 +16,51 @@ function rateHintFor(memoryId: string): string {
   return `memory_rate(id="${memoryId}", useful=true|false)`;
 }
 
-export const memorySearchOutputSchema = z.object({
+type MemorySearchResult = {
+  id: string;
+  name: string;
+  summary: string | null;
+  source: string;
+  scope: string;
+  similarity?: number;
+  retrievalSource?: string;
+  tags?: string[];
+  createdAt: string;
+  rateHint?: string;
+};
+
+function renderResults(results: MemorySearchResult[]): string | undefined {
+  if (results.length === 0) return undefined;
+  return results
+    .map((r) => {
+      const score = typeof r.similarity === "number" ? ` score=${r.similarity.toFixed(3)}` : "";
+      const summary = r.summary ? ` — ${r.summary}` : "";
+      return `- ${r.id} [${r.source}/${r.scope}]${score}${summary}`;
+    })
+    .join("\n");
+}
+
+export const memorySearchOutputSchema = swarmToolOutputSchema({
   // Plain string, NOT .uuid(): agents may join with custom IDs (AGENT_ID env /
   // join-swarm agentId), and a UUID constraint here makes the response fail MCP
   // output validation after the handler already ran.
   yourAgentId: z.string().optional(),
-  success: z.boolean(),
-  message: z.string(),
   results: z
     .array(
-      z.object({
-        id: z.string().uuid(),
-        name: z.string(),
-        summary: z.string().nullable(),
-        source: AgentMemorySourceSchema,
-        scope: AgentMemoryScopeSchema,
+      z.looseObject({
+        id: z.string().optional(),
+        name: z.string().optional(),
+        summary: z.string().nullable().optional(),
+        source: AgentMemorySourceSchema.optional(),
+        scope: AgentMemoryScopeSchema.optional(),
         similarity: z.number().optional(),
         retrievalSource: z.enum(["vec", "fts", "hybrid", "fallback", "graph"]).optional(),
         tags: z.array(z.string()).optional(),
-        createdAt: z.string(),
+        createdAt: z.string().optional(),
         rateHint: z.string().optional(),
       }),
     )
     .optional(),
-  _ratingNudge: z.string().optional(),
 });
 
 export const registerMemorySearchTool = (server: McpServer) => {
@@ -72,14 +93,7 @@ export const registerMemorySearchTool = (server: McpServer) => {
     },
     async ({ query, intent, scope, limit, source }, requestInfo, _meta) => {
       if (!requestInfo.agentId) {
-        return {
-          content: [{ type: "text", text: "Agent ID required for memory search." }],
-          structuredContent: {
-            yourAgentId: undefined,
-            success: false,
-            message: "Agent ID required. Are you registered in the swarm?",
-          },
-        };
+        return toolErr("Agent ID required. Are you registered in the swarm?");
       }
 
       const agent = getAgentById(requestInfo.agentId);
@@ -146,25 +160,12 @@ export const registerMemorySearchTool = (server: McpServer) => {
             : {}),
         }));
 
-        const nudgeCount = mapped.filter((r) => r.rateHint).length;
-        const _ratingNudge =
-          nudgeCount > 0 ? "Rate memories that help or mislead you with memory_rate." : undefined;
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Found ${mapped.length} memories matching "${query}".`,
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: `Found ${mapped.length} memories matching "${query}".`,
-            results: mapped,
-            _ratingNudge,
-          },
-        };
+        // The conditional rating steer lives in the central NUDGES map
+        // (src/tools/utils.ts), keyed off rateHint presence in the results.
+        return toolOk(`Found ${mapped.length} memories matching "${query}".`, {
+          details: renderResults(mapped),
+          data: { yourAgentId: requestInfo.agentId, results: mapped },
+        });
       }
 
       // Fallback: list recent memories (no OPENAI_API_KEY and no FTS hit)
@@ -185,20 +186,13 @@ export const registerMemorySearchTool = (server: McpServer) => {
         createdAt: r.createdAt,
       }));
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Embedding unavailable. Showing ${mapped.length} most recent memories.`,
-          },
-        ],
-        structuredContent: {
-          yourAgentId: requestInfo.agentId,
-          success: true,
-          message: `Embedding unavailable (no OPENAI_API_KEY). Showing ${mapped.length} most recent memories.`,
-          results: mapped,
+      return toolOk(
+        `Embedding unavailable (no OPENAI_API_KEY). Showing ${mapped.length} most recent memories.`,
+        {
+          details: renderResults(mapped),
+          data: { yourAgentId: requestInfo.agentId, results: mapped },
         },
-      };
+      );
     },
   );
 };