@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/tests/x402-config.test.ts

@@ -0,0 +1,182 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { loadX402Config } from "../x402/config.ts";
+
+describe("loadX402Config", () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    // Clear x402-related env vars before each test
+    delete process.env.EVM_PRIVATE_KEY;
+    delete process.env.X402_MAX_AUTO_APPROVE;
+    delete process.env.X402_DAILY_LIMIT;
+    delete process.env.X402_NETWORK;
+    delete process.env.X402_SIGNER_TYPE;
+    delete process.env.OPENFORT_API_KEY;
+    delete process.env.OPENFORT_WALLET_SECRET;
+    delete process.env.OPENFORT_WALLET_ADDRESS;
+  });
+
+  afterEach(() => {
+    // Restore original env
+    process.env = { ...originalEnv };
+  });
+
+  test("throws when no signer credentials are set", () => {
+    expect(() => loadX402Config()).toThrow("x402 payment requires either Openfort credentials");
+  });
+
+  // --- Viem signer tests ---
+
+  test("auto-detects viem signer when EVM_PRIVATE_KEY is set", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+
+    const config = loadX402Config();
+    expect(config.signerType).toBe("viem");
+    expect(config.evmPrivateKey).toBe(
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
+    );
+  });
+
+  test("throws when EVM_PRIVATE_KEY does not start with 0x", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "deadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    expect(() => loadX402Config()).toThrow("EVM_PRIVATE_KEY must start with '0x'");
+  });
+
+  test("returns config with defaults when only EVM_PRIVATE_KEY is set", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+
+    const config = loadX402Config();
+
+    expect(config.signerType).toBe("viem");
+    expect(config.maxAutoApprove).toBe(1.0);
+    expect(config.dailyLimit).toBe(10.0);
+    expect(config.network).toBe("eip155:84532");
+  });
+
+  // --- Openfort signer tests ---
+
+  test("auto-detects openfort signer when OPENFORT_API_KEY is set", () => {
+    process.env.OPENFORT_API_KEY = "sk_test_abc123";
+    process.env.OPENFORT_WALLET_SECRET = "base64secret";
+
+    const config = loadX402Config();
+    expect(config.signerType).toBe("openfort");
+    expect(config.openfortApiKey).toBe("sk_test_abc123");
+    expect(config.openfortWalletSecret).toBe("base64secret");
+  });
+
+  test("openfort takes priority over viem when both are set", () => {
+    process.env.OPENFORT_API_KEY = "sk_test_abc123";
+    process.env.OPENFORT_WALLET_SECRET = "base64secret";
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+
+    const config = loadX402Config();
+    expect(config.signerType).toBe("openfort");
+  });
+
+  test("throws when openfort signer is selected but OPENFORT_WALLET_SECRET is missing", () => {
+    process.env.OPENFORT_API_KEY = "sk_test_abc123";
+    expect(() => loadX402Config()).toThrow("OPENFORT_WALLET_SECRET is required");
+  });
+
+  test("includes OPENFORT_WALLET_ADDRESS when set", () => {
+    process.env.OPENFORT_API_KEY = "sk_test_abc123";
+    process.env.OPENFORT_WALLET_SECRET = "base64secret";
+    process.env.OPENFORT_WALLET_ADDRESS = "0x1234567890abcdef1234567890abcdef12345678";
+
+    const config = loadX402Config();
+    expect(config.openfortWalletAddress).toBe("0x1234567890abcdef1234567890abcdef12345678");
+  });
+
+  // --- Explicit signer type ---
+
+  test("respects explicit X402_SIGNER_TYPE=viem", () => {
+    process.env.X402_SIGNER_TYPE = "viem";
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    process.env.OPENFORT_API_KEY = "sk_test_abc123";
+
+    const config = loadX402Config();
+    expect(config.signerType).toBe("viem");
+  });
+
+  test("throws on invalid X402_SIGNER_TYPE", () => {
+    process.env.X402_SIGNER_TYPE = "invalid";
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    expect(() => loadX402Config()).toThrow('X402_SIGNER_TYPE must be "openfort" or "viem"');
+  });
+
+  // --- Spending limit tests ---
+
+  test("parses custom X402_MAX_AUTO_APPROVE", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    process.env.X402_MAX_AUTO_APPROVE = "5.50";
+
+    const config = loadX402Config();
+    expect(config.maxAutoApprove).toBe(5.5);
+  });
+
+  test("parses custom X402_DAILY_LIMIT", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    process.env.X402_DAILY_LIMIT = "25.00";
+
+    const config = loadX402Config();
+    expect(config.dailyLimit).toBe(25.0);
+  });
+
+  test("uses custom X402_NETWORK", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    process.env.X402_NETWORK = "eip155:8453";
+
+    const config = loadX402Config();
+    expect(config.network).toBe("eip155:8453");
+  });
+
+  test("throws when X402_MAX_AUTO_APPROVE is not a valid number", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    process.env.X402_MAX_AUTO_APPROVE = "abc";
+
+    expect(() => loadX402Config()).toThrow("X402_MAX_AUTO_APPROVE must be a positive number");
+  });
+
+  test("throws when X402_MAX_AUTO_APPROVE is zero", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    process.env.X402_MAX_AUTO_APPROVE = "0";
+
+    expect(() => loadX402Config()).toThrow("X402_MAX_AUTO_APPROVE must be a positive number");
+  });
+
+  test("throws when X402_MAX_AUTO_APPROVE is negative", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    process.env.X402_MAX_AUTO_APPROVE = "-1";
+
+    expect(() => loadX402Config()).toThrow("X402_MAX_AUTO_APPROVE must be a positive number");
+  });
+
+  test("throws when X402_DAILY_LIMIT is not a valid number", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    process.env.X402_DAILY_LIMIT = "not-a-number";
+
+    expect(() => loadX402Config()).toThrow("X402_DAILY_LIMIT must be a positive number");
+  });
+
+  test("throws when X402_DAILY_LIMIT is zero", () => {
+    process.env.EVM_PRIVATE_KEY =
+      "0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678";
+    process.env.X402_DAILY_LIMIT = "0";
+
+    expect(() => loadX402Config()).toThrow("X402_DAILY_LIMIT must be a positive number");
+  });
+});

package/src/tests/x402-spending-tracker.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, test } from "bun:test";
+import { SpendingTracker } from "../x402/spending-tracker.ts";
+
+describe("SpendingTracker", () => {
+  describe("checkSpendingLimit", () => {
+    test("returns null when payment is within limits", () => {
+      const tracker = new SpendingTracker(5.0, 50.0);
+      const result = tracker.checkSpendingLimit(3.0, "https://api.example.com");
+      expect(result).toBeNull();
+    });
+
+    test("blocks payment exceeding per-request limit", () => {
+      const tracker = new SpendingTracker(1.0, 50.0);
+      const result = tracker.checkSpendingLimit(2.0, "https://api.example.com");
+
+      expect(result).not.toBeNull();
+      expect(result).toContain("exceeds per-request limit");
+      expect(result).toContain("$2.00");
+      expect(result).toContain("$1.00");
+    });
+
+    test("blocks payment that would exceed daily limit", () => {
+      const tracker = new SpendingTracker(10.0, 5.0);
+      // Record some existing spending
+      tracker.recordPayment(4.0, "https://api.example.com/first");
+
+      const result = tracker.checkSpendingLimit(2.0, "https://api.example.com/second");
+
+      expect(result).not.toBeNull();
+      expect(result).toContain("would exceed daily limit");
+      expect(result).toContain("$5.00");
+      expect(result).toContain("Already spent today: $4.00");
+    });
+
+    test("allows payment exactly at per-request limit", () => {
+      const tracker = new SpendingTracker(1.0, 50.0);
+      const result = tracker.checkSpendingLimit(1.0, "https://api.example.com");
+      expect(result).toBeNull();
+    });
+
+    test("allows payment that exactly fills daily limit", () => {
+      const tracker = new SpendingTracker(10.0, 10.0);
+      tracker.recordPayment(5.0, "https://api.example.com/first");
+
+      const result = tracker.checkSpendingLimit(5.0, "https://api.example.com/second");
+      expect(result).toBeNull();
+    });
+
+    test("includes URL in error messages", () => {
+      const tracker = new SpendingTracker(1.0, 50.0);
+      const result = tracker.checkSpendingLimit(5.0, "https://paid-api.io/data");
+
+      expect(result).toContain("https://paid-api.io/data");
+    });
+  });
+
+  describe("recordPayment", () => {
+    test("records a payment and updates today spending", () => {
+      const tracker = new SpendingTracker(10.0, 100.0);
+      expect(tracker.getTodaySpending()).toBe(0);
+
+      tracker.recordPayment(3.5, "https://api.example.com");
+      expect(tracker.getTodaySpending()).toBe(3.5);
+    });
+
+    test("accumulates multiple payments", () => {
+      const tracker = new SpendingTracker(10.0, 100.0);
+
+      tracker.recordPayment(1.0, "https://api.example.com/a");
+      tracker.recordPayment(2.5, "https://api.example.com/b");
+      tracker.recordPayment(0.75, "https://api.example.com/c");
+
+      expect(tracker.getTodaySpending()).toBeCloseTo(4.25, 10);
+    });
+  });
+
+  describe("getTodayRecords", () => {
+    test("returns empty array when no payments recorded", () => {
+      const tracker = new SpendingTracker(10.0, 100.0);
+      expect(tracker.getTodayRecords()).toHaveLength(0);
+    });
+
+    test("returns records from today", () => {
+      const tracker = new SpendingTracker(10.0, 100.0);
+      tracker.recordPayment(1.0, "https://api.example.com/a");
+      tracker.recordPayment(2.0, "https://api.example.com/b");
+
+      const records = tracker.getTodayRecords();
+      expect(records).toHaveLength(2);
+      expect(records[0]!.amount).toBe(1.0);
+      expect(records[0]!.url).toBe("https://api.example.com/a");
+      expect(records[1]!.amount).toBe(2.0);
+      expect(records[1]!.url).toBe("https://api.example.com/b");
+    });
+
+    test("records have timestamps", () => {
+      const tracker = new SpendingTracker(10.0, 100.0);
+      const before = Date.now();
+      tracker.recordPayment(1.0, "https://api.example.com");
+      const after = Date.now();
+
+      const records = tracker.getTodayRecords();
+      expect(records[0]!.timestamp).toBeGreaterThanOrEqual(before);
+      expect(records[0]!.timestamp).toBeLessThanOrEqual(after);
+    });
+  });
+
+  describe("getSummary", () => {
+    test("returns correct initial summary", () => {
+      const tracker = new SpendingTracker(2.0, 20.0);
+      const summary = tracker.getSummary();
+
+      expect(summary.todaySpent).toBe(0);
+      expect(summary.todayCount).toBe(0);
+      expect(summary.dailyLimit).toBe(20.0);
+      expect(summary.maxPerRequest).toBe(2.0);
+      expect(summary.dailyRemaining).toBe(20.0);
+    });
+
+    test("reflects spending after payments", () => {
+      const tracker = new SpendingTracker(5.0, 15.0);
+      tracker.recordPayment(3.0, "https://api.example.com/a");
+      tracker.recordPayment(4.0, "https://api.example.com/b");
+
+      const summary = tracker.getSummary();
+      expect(summary.todaySpent).toBe(7.0);
+      expect(summary.todayCount).toBe(2);
+      expect(summary.dailyRemaining).toBe(8.0);
+    });
+
+    test("dailyRemaining does not go negative", () => {
+      const tracker = new SpendingTracker(20.0, 5.0);
+      // Force recording above limit (bypasses check)
+      tracker.recordPayment(8.0, "https://api.example.com");
+
+      const summary = tracker.getSummary();
+      expect(summary.dailyRemaining).toBe(0);
+    });
+  });
+
+  describe("pruneOldRecords", () => {
+    test("removes records older than 48 hours on next recordPayment", () => {
+      const tracker = new SpendingTracker(100.0, 1000.0);
+
+      // Manually access the internal records to inject an old record
+      // @ts-expect-error accessing private field for testing
+      tracker.records.push({
+        timestamp: Date.now() - 49 * 60 * 60 * 1000, // 49 hours ago
+        amount: 50.0,
+        url: "https://old.example.com",
+      });
+
+      // Verify the old record is there
+      // @ts-expect-error accessing private field for testing
+      expect(tracker.records).toHaveLength(1);
+
+      // Recording a new payment triggers pruning
+      tracker.recordPayment(1.0, "https://new.example.com");
+
+      // Old record should be pruned, only new one remains
+      // @ts-expect-error accessing private field for testing
+      expect(tracker.records).toHaveLength(1);
+      // @ts-expect-error accessing private field for testing
+      expect(tracker.records[0].url).toBe("https://new.example.com");
+    });
+
+    test("keeps records within 48 hours", () => {
+      const tracker = new SpendingTracker(100.0, 1000.0);
+
+      // Inject a record from 47 hours ago (should survive)
+      // @ts-expect-error accessing private field for testing
+      tracker.records.push({
+        timestamp: Date.now() - 47 * 60 * 60 * 1000,
+        amount: 5.0,
+        url: "https://recent.example.com",
+      });
+
+      tracker.recordPayment(1.0, "https://new.example.com");
+
+      // Both records should remain
+      // @ts-expect-error accessing private field for testing
+      expect(tracker.records).toHaveLength(2);
+    });
+  });
+});

package/src/tools/cancel-task.ts

@@ -18,6 +18,8 @@ export const registerCancelTaskTool = (server: McpServer) => {
       title: "Cancel Task",
       description:
         "Cancel a task that is pending or in progress. Only the lead or task creator can cancel tasks. The worker will be notified via hooks.",
+      annotations: { destructiveHint: true },
+
       inputSchema: z.object({
         taskId: z.uuid().describe("The ID of the task to cancel."),
         reason: z.string().optional().describe("Reason for cancellation."),

package/src/tools/context-diff.ts

@@ -0,0 +1,171 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getContextVersion } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+async function computeDiff(oldContent: string, newContent: string): Promise<string> {
+  const tmpDir = tmpdir();
+  const oldPath = join(tmpDir, `ctx-diff-old-${crypto.randomUUID()}.txt`);
+  const newPath = join(tmpDir, `ctx-diff-new-${crypto.randomUUID()}.txt`);
+
+  try {
+    await Bun.write(oldPath, oldContent);
+    await Bun.write(newPath, newContent);
+
+    const proc = Bun.spawn(["diff", "-u", "--label", "old", "--label", "new", oldPath, newPath], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const output = await new Response(proc.stdout).text();
+    await proc.exited;
+
+    // diff returns exit code 1 when files differ — that's expected
+    return output || "(no differences)";
+  } finally {
+    // Clean up temp files
+    try {
+      const { unlink } = await import("node:fs/promises");
+      await unlink(oldPath);
+      await unlink(newPath);
+    } catch {
+      /* ignore cleanup errors */
+    }
+  }
+}
+
+export const registerContextDiffTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "context-diff",
+    {
+      title: "Context Diff",
+      description:
+        "Compare two versions of a context file. Shows a unified diff between the specified version and its predecessor (or a specific comparison version).",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        versionId: z.string().uuid().describe('The "newer" version ID to diff.'),
+        compareToVersionId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe('The "older" version ID to compare against. Default: previous version.'),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        field: z.string().optional(),
+        fromVersion: z.number().optional(),
+        toVersion: z.number().optional(),
+        diff: z.string().optional(),
+        changeSource: z.string().optional(),
+        createdAt: z.string().optional(),
+      }),
+    },
+    async ({ versionId, compareToVersionId }, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: 'Agent ID not found. Set the "X-Agent-ID" header.' }],
+          structuredContent: {
+            success: false,
+            message: 'Agent ID not found. Set the "X-Agent-ID" header.',
+          },
+        };
+      }
+
+      // Get the target version
+      const version = getContextVersion(versionId);
+      if (!version) {
+        return {
+          content: [{ type: "text", text: `Version ${versionId} not found.` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Version ${versionId} not found.`,
+          },
+        };
+      }
+
+      // Access control: agents can diff their own context, lead can diff any
+      if (version.agentId !== requestInfo.agentId) {
+        const callerAgent = getAgentById(requestInfo.agentId);
+        if (!callerAgent?.isLead) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Permission denied. Only the lead can diff other agents' context.",
+              },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Permission denied. Only the lead can diff other agents' context.",
+            },
+          };
+        }
+      }
+
+      // Get the comparison version
+      let compareVersion: import("@/types").ContextVersion | null | undefined;
+      if (compareToVersionId) {
+        compareVersion = getContextVersion(compareToVersionId);
+        if (!compareVersion) {
+          return {
+            content: [
+              { type: "text", text: `Comparison version ${compareToVersionId} not found.` },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `Comparison version ${compareToVersionId} not found.`,
+            },
+          };
+        }
+        if (compareVersion.agentId !== version.agentId || compareVersion.field !== version.field) {
+          return {
+            content: [
+              { type: "text", text: "Both versions must be for the same agent and field." },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Both versions must be for the same agent and field.",
+            },
+          };
+        }
+      } else if (version.previousVersionId) {
+        compareVersion = getContextVersion(version.previousVersionId);
+      }
+
+      const oldContent = compareVersion?.content ?? "";
+      const diff = await computeDiff(oldContent, version.content);
+
+      const fromVersion = compareVersion?.version ?? 0;
+      const toVersion = version.version;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Diff for ${version.field} v${fromVersion} → v${toVersion}:\n\n${diff}`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Diff computed for ${version.field} v${fromVersion} → v${toVersion}.`,
+          field: version.field,
+          fromVersion,
+          toVersion,
+          diff,
+          changeSource: version.changeSource,
+          createdAt: version.createdAt,
+        },
+      };
+    },
+  );
+};

package/src/tools/context-history.ts

@@ -0,0 +1,138 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getContextVersionHistory } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import type { VersionableField } from "@/types";
+
+export const registerContextHistoryTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "context-history",
+    {
+      title: "Context History",
+      description:
+        "View version history for an agent's context files (soulMd, identityMd, toolsMd, claudeMd, setupScript). Returns metadata for each version without full content.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        agentId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe("Agent ID to query. Default: your own agent. Lead can query any agent."),
+        field: z
+          .enum(["soulMd", "identityMd", "toolsMd", "claudeMd", "setupScript"])
+          .optional()
+          .describe("Filter by specific field. Omit for all fields."),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(100)
+          .optional()
+          .describe("Max versions to return (default: 10)."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        versions: z
+          .array(
+            z.object({
+              id: z.string().uuid(),
+              field: z.string(),
+              version: z.number(),
+              changeSource: z.string(),
+              changedByAgentId: z.string().uuid().nullable(),
+              changeReason: z.string().nullable(),
+              contentLength: z.number(),
+              createdAt: z.string(),
+            }),
+          )
+          .optional(),
+      }),
+    },
+    async ({ agentId, field, limit }, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: 'Agent ID not found. Set the "X-Agent-ID" header.' }],
+          structuredContent: {
+            success: false,
+            message: 'Agent ID not found. Set the "X-Agent-ID" header.',
+          },
+        };
+      }
+
+      const targetAgentId = agentId ?? requestInfo.agentId;
+
+      // Verify target agent exists
+      const targetAgent = getAgentById(targetAgentId);
+      if (!targetAgent) {
+        return {
+          content: [{ type: "text", text: "Agent not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Agent not found.",
+          },
+        };
+      }
+
+      // Access control: agents can see their own history, lead can see any
+      if (targetAgentId !== requestInfo.agentId) {
+        const callerAgent = getAgentById(requestInfo.agentId);
+        if (!callerAgent?.isLead) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Permission denied. Only the lead can view other agents' context history.",
+              },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Permission denied. Only the lead can view other agents' context history.",
+            },
+          };
+        }
+      }
+
+      const versions = getContextVersionHistory({
+        agentId: targetAgentId,
+        field: field as VersionableField | undefined,
+        limit: limit ?? 10,
+      });
+
+      const versionSummaries = versions.map((v) => ({
+        id: v.id,
+        field: v.field,
+        version: v.version,
+        changeSource: v.changeSource,
+        changedByAgentId: v.changedByAgentId,
+        changeReason: v.changeReason,
+        contentLength: v.content.length,
+        createdAt: v.createdAt,
+      }));
+
+      const text =
+        versions.length === 0
+          ? `No context versions found for agent ${targetAgentId}${field ? ` field ${field}` : ""}.`
+          : versionSummaries
+              .map(
+                (v) =>
+                  `v${v.version} ${v.field} [${v.changeSource}] ${v.createdAt} (${v.contentLength} chars)${v.changeReason ? ` — ${v.changeReason}` : ""}`,
+              )
+              .join("\n");
+
+      return {
+        content: [{ type: "text", text }],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Found ${versions.length} version(s).`,
+          versions: versionSummaries,
+        },
+      };
+    },
+  );
+};

package/src/tools/create-channel.ts

@@ -9,6 +9,7 @@ export const registerCreateChannelTool = (server: McpServer) => {
     "create-channel",
     {
       title: "Create Channel",
+      annotations: { destructiveHint: false },
       description: "Creates a new channel for cross-agent communication.",
       inputSchema: z.object({
         name: z.string().min(1).max(100).describe("Channel name (must be unique)."),