@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/scripts/generate-openapi.ts

@@ -0,0 +1,26 @@
+import { generateOpenApiSpec } from "../src/http/openapi";
+// Import all handler files to trigger route() registrations
+import "../src/http/active-sessions";
+import "../src/http/agents";
+import "../src/http/config";
+import "../src/http/db-query";
+import "../src/http/ecosystem";
+import "../src/http/epics";
+import "../src/http/memory";
+import "../src/http/poll";
+import "../src/http/repos";
+import "../src/http/schedules";
+import "../src/http/session-data";
+import "../src/http/stats";
+import "../src/http/tasks";
+import "../src/http/trackers/linear";
+import "../src/http/webhooks";
+import "../src/http/workflows";
+
+const version = (await Bun.file("package.json").json()).version;
+const spec = generateOpenApiSpec({ version, serverUrl: "http://localhost:3013" });
+await Bun.write("openapi.json", spec);
+console.log(`Generated openapi.json (${(spec.length / 1024).toFixed(1)}KB)`);
+
+// Auto-generate docs-site API reference from the new spec
+await Bun.$`bun docs-site/scripts/generate-docs.ts`;

package/scripts/measure-tool-tokens.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env bun
+/**
+ * Measures token overhead from MCP tool definitions.
+ *
+ * Uses a simple heuristic: ~4 characters per token (GPT/Claude approximation).
+ * For exact counts, use tiktoken or the Anthropic tokenizer.
+ *
+ * Usage: bun scripts/measure-tool-tokens.ts
+ */
+
+import { closeDb, initDb } from "../src/be/db";
+import { createServer } from "../src/server";
+import { CORE_TOOLS, DEFERRED_TOOLS } from "../src/tools/tool-config";
+
+const DB_PATH = "./measure-tokens-temp.sqlite";
+
+// Simple token estimation: ~4 chars per token for English text + JSON
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+async function main() {
+  // Initialize DB and server to get registered tools
+  initDb(DB_PATH);
+  const server = createServer();
+
+  const tools = (server as unknown as { _registeredTools: Record<string, unknown> })
+    ._registeredTools;
+
+  const toolNames = Object.keys(tools);
+
+  // Build tool definitions as they'd appear in the tools/list response
+  let totalChars = 0;
+  let coreChars = 0;
+  let deferredChars = 0;
+  let coreCount = 0;
+  let deferredCount = 0;
+
+  const toolSizes: { name: string; chars: number; tokens: number; classification: string }[] = [];
+
+  for (const name of toolNames) {
+    const tool = tools[name] as Record<string, unknown>;
+    // Serialize the tool definition as it would appear in the MCP response
+    const definition = JSON.stringify({
+      name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: tool.annotations,
+    });
+    const chars = definition.length;
+    const tokens = estimateTokens(definition);
+    const isCore = CORE_TOOLS.has(name);
+    const isDeferred = DEFERRED_TOOLS.has(name);
+
+    totalChars += chars;
+    if (isCore) {
+      coreChars += chars;
+      coreCount++;
+    } else if (isDeferred) {
+      deferredChars += chars;
+      deferredCount++;
+    }
+
+    toolSizes.push({
+      name,
+      chars,
+      tokens,
+      classification: isCore ? "CORE" : isDeferred ? "DEFERRED" : "UNCLASSIFIED",
+    });
+  }
+
+  // Sort by size descending
+  toolSizes.sort((a, b) => b.chars - a.chars);
+
+  console.log("=== MCP Tool Token Measurement ===\n");
+  console.log(`Total registered tools: ${toolNames.length}`);
+  console.log(`Core tools: ${coreCount}`);
+  console.log(`Deferred tools: ${deferredCount}`);
+  console.log();
+
+  const allTokens = Math.ceil(totalChars / 4);
+  const coreOnlyTokens = Math.ceil(coreChars / 4);
+  const deferredOnlyTokens = Math.ceil(deferredChars / 4);
+  const reduction = ((allTokens - coreOnlyTokens) / allTokens) * 100;
+
+  console.log("--- Token Estimates (JSON serialized, ~4 chars/token) ---\n");
+  console.log(`All tools:      ~${allTokens.toLocaleString()} tokens (${totalChars.toLocaleString()} chars)`);
+  console.log(`Core only:      ~${coreOnlyTokens.toLocaleString()} tokens (${coreChars.toLocaleString()} chars)`);
+  console.log(`Deferred only:  ~${deferredOnlyTokens.toLocaleString()} tokens (${deferredChars.toLocaleString()} chars)`);
+  console.log(`\nSavings:        ~${(allTokens - coreOnlyTokens).toLocaleString()} tokens (${reduction.toFixed(1)}% reduction)`);
+
+  console.log("\n--- Per-Tool Breakdown (sorted by size) ---\n");
+  console.log("  Tool Name".padEnd(35) + "Chars".padStart(8) + "Tokens".padStart(8) + "  Class");
+  console.log("-".repeat(70));
+  for (const t of toolSizes) {
+    const marker = t.classification === "CORE" ? "●" : "○";
+    console.log(
+      `  ${marker} ${t.name}`.padEnd(35) +
+        String(t.chars).padStart(8) +
+        String(t.tokens).padStart(8) +
+        `  ${t.classification}`,
+    );
+  }
+
+  // Cleanup
+  closeDb();
+  const { unlink } = await import("node:fs/promises");
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(DB_PATH + suffix);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+main().catch(console.error);

package/scripts/x402-e2e-test.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env bun
+/**
+ * x402 End-to-End Test
+ *
+ * Tests the full x402 payment flow:
+ *   1. Starts the dummy x402 test server
+ *   2. Creates an x402 client (with viem signer using a test key)
+ *   3. Makes a request to the paid endpoint
+ *   4. Verifies the 402 → sign → retry → 200 flow works
+ *
+ * Usage:
+ *   bun scripts/x402-e2e-test.ts
+ *
+ * Environment:
+ *   Set EVM_PRIVATE_KEY or OPENFORT_API_KEY + OPENFORT_WALLET_SECRET
+ *   If none set, uses a hardcoded test key (viem signer).
+ */
+
+import { createX402Client } from "../src/x402/client.ts";
+import type { Subprocess } from "bun";
+
+const TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+const SERVER_PORT = 4021;
+const BASE_URL = `http://localhost:${SERVER_PORT}`;
+
+let serverProcess: Subprocess | null = null;
+
+async function startServer(): Promise<void> {
+  serverProcess = Bun.spawn(["bun", "scripts/x402-test-server.ts", String(SERVER_PORT)], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  // Wait for server to be ready
+  for (let i = 0; i < 30; i++) {
+    try {
+      const res = await fetch(`${BASE_URL}/health`);
+      if (res.ok) return;
+    } catch {
+      // Server not ready yet
+    }
+    await Bun.sleep(100);
+  }
+  throw new Error("Server failed to start within 3 seconds");
+}
+
+function stopServer(): void {
+  if (serverProcess) {
+    serverProcess.kill();
+    serverProcess = null;
+  }
+}
+
+function log(msg: string): void {
+  console.log(`  ${msg}`);
+}
+
+function pass(name: string): void {
+  console.log(`  PASS  ${name}`);
+}
+
+function fail(name: string, error: unknown): void {
+  console.log(`  FAIL  ${name}: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+async function runTests(): Promise<{ passed: number; failed: number }> {
+  let passed = 0;
+  let failed = 0;
+
+  // Determine signer type
+  const hasOpenfort = !!process.env.OPENFORT_API_KEY;
+  const hasViem = !!process.env.EVM_PRIVATE_KEY;
+
+  if (!hasOpenfort && !hasViem) {
+    log(`No signer env vars set. Using test private key (viem signer).`);
+    process.env.EVM_PRIVATE_KEY = TEST_PRIVATE_KEY;
+  }
+
+  // Test 1: Free endpoint works
+  try {
+    const res = await fetch(`${BASE_URL}/`);
+    const body = await res.json();
+    if (res.status !== 200 || body.status !== "ok") throw new Error(`Expected 200 ok, got ${res.status}`);
+    pass("Free endpoint returns 200");
+    passed++;
+  } catch (e) {
+    fail("Free endpoint returns 200", e);
+    failed++;
+  }
+
+  // Test 2: Paid endpoint returns 402 without payment
+  try {
+    const res = await fetch(`${BASE_URL}/paid`);
+    if (res.status !== 402) throw new Error(`Expected 402, got ${res.status}`);
+    const body = await res.json();
+    if (!body.accepts || body.x402Version !== 2) throw new Error("Missing x402 payment requirements");
+    pass("Paid endpoint returns 402 without payment");
+    passed++;
+  } catch (e) {
+    fail("Paid endpoint returns 402 without payment", e);
+    failed++;
+  }
+
+  // Test 3: Full x402 flow with viem/openfort signer
+  try {
+    const client = await createX402Client();
+    log(`Using ${client.config.signerType} signer, wallet: ${client.walletAddress}`);
+
+    const res = await client.fetch(`${BASE_URL}/paid`);
+    const body = await res.json();
+
+    if (res.status !== 200) {
+      throw new Error(`Expected 200 after payment, got ${res.status}: ${JSON.stringify(body)}`);
+    }
+    if (!body.paymentAccepted) {
+      throw new Error("Server did not acknowledge payment acceptance");
+    }
+
+    pass(`Full x402 flow (${client.config.signerType} signer) → 200 with payment accepted`);
+    log(`  Payer: ${body.payer}`);
+    log(`  Amount: ${body.amount}`);
+    passed++;
+  } catch (e) {
+    fail("Full x402 flow", e);
+    failed++;
+  }
+
+  // Test 4: Spending tracker records payment
+  try {
+    const client = await createX402Client();
+    const summaryBefore = client.getSpendingSummary();
+    const countBefore = summaryBefore.todayCount;
+
+    await client.fetch(`${BASE_URL}/paid`);
+
+    const summaryAfter = client.getSpendingSummary();
+    if (summaryAfter.todayCount !== countBefore + 1) {
+      throw new Error(`Expected ${countBefore + 1} payments, got ${summaryAfter.todayCount}`);
+    }
+
+    pass("Spending tracker records payment");
+    log(`  Spent today: $${summaryAfter.todaySpent.toFixed(4)}`);
+    passed++;
+  } catch (e) {
+    fail("Spending tracker records payment", e);
+    failed++;
+  }
+
+  // Test 5: Expensive endpoint blocked by spending limit (default $1.00/request)
+  try {
+    const client = await createX402Client();
+
+    const res = await client.fetch(`${BASE_URL}/paid/expensive`);
+    // The spending tracker should block this since $5 > $1 per-request limit
+    // The x402 client will throw or return an error
+    // Actually, the abort happens in the hook which throws
+    fail("Expensive endpoint should be blocked by spending limit", "No error thrown");
+    failed++;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (msg.includes("exceeds per-request limit") || msg.includes("abort") || msg.includes("Failed to create payment")) {
+      pass("Expensive endpoint blocked by spending limit ($5 > $1 max)");
+      passed++;
+    } else {
+      fail("Expensive endpoint blocked by spending limit", e);
+      failed++;
+    }
+  }
+
+  return { passed, failed };
+}
+
+async function main() {
+  console.log("x402 End-to-End Test");
+  console.log("====================\n");
+
+  console.log("Starting test server...");
+  await startServer();
+  console.log(`Server running on ${BASE_URL}\n`);
+
+  try {
+    const { passed, failed } = await runTests();
+    console.log(`\nResults: ${passed} passed, ${failed} failed`);
+    process.exitCode = failed > 0 ? 1 : 0;
+  } finally {
+    stopServer();
+    console.log("Server stopped.");
+  }
+}
+
+main().catch((error) => {
+  console.error("Fatal:", error instanceof Error ? error.message : String(error));
+  stopServer();
+  process.exit(1);
+});

package/scripts/x402-test-server.ts

@@ -0,0 +1,236 @@
+#!/usr/bin/env bun
+/**
+ * Dummy x402 Test Server
+ *
+ * A minimal HTTP server with an x402-protected endpoint for testing the payment flow.
+ * Does NOT settle on-chain — just verifies the EIP-712 signature from the payment header.
+ *
+ * Endpoints:
+ *   GET /              — Free endpoint (returns 200)
+ *   GET /paid          — x402-protected endpoint (returns 402, then 200 with valid payment)
+ *   GET /paid/expensive — x402-protected with higher price ($5 USDC)
+ *
+ * Usage:
+ *   bun scripts/x402-test-server.ts [port]
+ *
+ * Default port: 4020
+ */
+
+import { getAddress, verifyTypedData } from "viem";
+import { encodePaymentRequiredHeader } from "@x402/core/http";
+
+const PORT = Number.parseInt(process.argv[2] || "4020", 10);
+
+// A well-known test address to use as payTo (doesn't need to be real for testing)
+const PAY_TO = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"; // vitalik.eth
+
+// USDC on Base Sepolia — EIP-712 domain params
+const USDC_ADDRESS = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+const USDC_NAME = "USD Coin";
+const USDC_VERSION = "2";
+const CHAIN_ID = 84532; // Base Sepolia
+
+// EIP-3009 TransferWithAuthorization types
+const authorizationTypes = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ],
+} as const;
+
+interface PaymentRequired {
+  x402Version: number;
+  resource: { url: string; description: string; mimeType: string };
+  accepts: Array<{
+    scheme: string;
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+  }>;
+}
+
+function buildPaymentRequired(url: string, amount: string): PaymentRequired {
+  return {
+    x402Version: 2,
+    resource: {
+      url,
+      description: "Premium test content",
+      mimeType: "application/json",
+    },
+    accepts: [
+      {
+        scheme: "exact",
+        network: "eip155:84532", // Base Sepolia
+        asset: USDC_ADDRESS,
+        amount,
+        payTo: PAY_TO,
+        maxTimeoutSeconds: 86400,
+        extra: {
+          // EIP-712 domain params required by the x402 exact EVM scheme
+          name: USDC_NAME,
+          version: USDC_VERSION,
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * Decode a base64-encoded payment payload from the PAYMENT-SIGNATURE header.
+ */
+function decodePaymentHeader(headerValue: string): Record<string, unknown> | null {
+  try {
+    const json = atob(headerValue);
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify the EIP-3009 TransferWithAuthorization signature in the payment payload.
+ *
+ * The x402 exact EVM scheme creates a payload like:
+ *   { authorization: { from, to, value, validAfter, validBefore, nonce }, signature: "0x..." }
+ */
+async function verifyPayment(paymentPayload: Record<string, unknown>): Promise<{
+  valid: boolean;
+  payer?: string;
+  reason?: string;
+}> {
+  try {
+    const payload = paymentPayload.payload as Record<string, unknown>;
+    if (!payload) {
+      return { valid: false, reason: "missing payload" };
+    }
+
+    const signature = payload.signature as `0x${string}`;
+    const authorization = payload.authorization as Record<string, unknown>;
+
+    if (!signature) {
+      return { valid: false, reason: "missing signature in payload" };
+    }
+    if (!authorization) {
+      // No authorization data — accept the payment header as-is (basic test mode)
+      return { valid: true, payer: "unknown (signature present, no authorization data)" };
+    }
+
+    // Reconstruct the EIP-712 typed data and verify the signature
+    const domain = {
+      name: USDC_NAME,
+      version: USDC_VERSION,
+      chainId: BigInt(CHAIN_ID),
+      verifyingContract: getAddress(USDC_ADDRESS),
+    };
+
+    const message = {
+      from: getAddress(authorization.from as string),
+      to: getAddress(authorization.to as string),
+      value: BigInt(authorization.value as string),
+      validAfter: BigInt(authorization.validAfter as string),
+      validBefore: BigInt(authorization.validBefore as string),
+      nonce: authorization.nonce as `0x${string}`,
+    };
+
+    const valid = await verifyTypedData({
+      address: message.from,
+      domain,
+      types: authorizationTypes,
+      primaryType: "TransferWithAuthorization",
+      message,
+      signature,
+    });
+
+    return { valid, payer: message.from };
+  } catch (error) {
+    return {
+      valid: false,
+      reason: `verification error: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+const server = Bun.serve({
+  port: PORT,
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    // Free endpoint
+    if (url.pathname === "/" || url.pathname === "/health") {
+      return Response.json({ status: "ok", message: "x402 test server running" });
+    }
+
+    // Paid endpoints
+    if (url.pathname.startsWith("/paid")) {
+      const isExpensive = url.pathname === "/paid/expensive";
+      const amount = isExpensive ? "5000000" : "10000"; // $5.00 or $0.01 USDC (6 decimals)
+
+      // Check for payment header
+      const paymentHeader =
+        req.headers.get("PAYMENT-SIGNATURE") || req.headers.get("X-PAYMENT");
+
+      if (!paymentHeader) {
+        // No payment — return 402 with payment requirements
+        const paymentRequired = buildPaymentRequired(
+          `${url.origin}${url.pathname}`,
+          amount,
+        );
+
+        // x402 v2 requires the PAYMENT-REQUIRED header (base64-encoded PaymentRequired)
+        const encoded = encodePaymentRequiredHeader(
+          paymentRequired as Parameters<typeof encodePaymentRequiredHeader>[0],
+        );
+
+        return new Response(JSON.stringify(paymentRequired), {
+          status: 402,
+          headers: {
+            "Content-Type": "application/json",
+            "PAYMENT-REQUIRED": encoded,
+          },
+        });
+      }
+
+      // Has payment header — decode and verify
+      const paymentPayload = decodePaymentHeader(paymentHeader);
+      if (!paymentPayload) {
+        return Response.json(
+          { error: "Invalid payment header (could not decode base64/JSON)" },
+          { status: 400 },
+        );
+      }
+
+      const verification = await verifyPayment(paymentPayload);
+
+      if (!verification.valid) {
+        return Response.json(
+          { error: `Payment verification failed: ${verification.reason}` },
+          { status: 402 },
+        );
+      }
+
+      // Payment accepted — return the premium content
+      return Response.json({
+        content: isExpensive ? "This is expensive premium content!" : "This is paid content!",
+        paymentAccepted: true,
+        payer: verification.payer,
+        amount: isExpensive ? "$5.00" : "$0.01",
+      });
+    }
+
+    return Response.json({ error: "Not found" }, { status: 404 });
+  },
+});
+
+console.log(`x402 test server running on http://localhost:${server.port}`);
+console.log("Endpoints:");
+console.log("  GET /              Free endpoint");
+console.log("  GET /paid          x402-protected ($0.01 USDC)");
+console.log("  GET /paid/expensive  x402-protected ($5.00 USDC)");
+console.log("\nPress Ctrl+C to stop.");