@desplega.ai/agent-swarm 1.88.0 → 1.89.0

package/src/tests/workflow-async-v2.test.ts

@@ -4,6 +4,7 @@ import { z } from "zod";
 import {
   closeDb,
   completeTask,
+  createUser,
   createWorkflow,
   deleteWorkflow,
   getTaskByWorkflowRunStepId,
@@ -151,6 +152,28 @@ describe("Workflow Async v2 (Phase 4)", () => {
       expect(task!.task).toBe("Do the thing");
     });
 
+    test("inherits requestedByUserId from workflow execution options", async () => {
+      const user = createUser({ name: "Workflow Requester" });
+      const workflow = makeWorkflow({
+        nodes: [
+          {
+            id: "task1",
+            type: "agent-task",
+            config: { template: "Do attributed workflow work" },
+          },
+        ],
+      });
+
+      const runId = await startWorkflowExecution(workflow, { test: true }, registry, {
+        requestedByUserId: user.id,
+      });
+      const steps = getWorkflowRunStepsByRunId(runId);
+      const task = getTaskByWorkflowRunStepId(steps[0]!.id);
+
+      expect(task).toBeTruthy();
+      expect(task!.requestedByUserId).toBe(user.id);
+    });
+
     test("workflow pauses at waiting when hitting async executor", async () => {
       const workflow = makeWorkflow({
         nodes: [

package/src/tests/x-composio.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import { parseComposioArgs, runComposioCommand, runXCommand } from "../commands/x";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("parseComposioArgs", () => {
+  test("parses method, path, body, query, and base url", () => {
+    const parsed = parseComposioArgs(
+      [
+        "POST",
+        "/tools/execute/GITHUB_CREATE_AN_ISSUE",
+        "--body",
+        '{"arguments":{"title":"demo"}}',
+        "--query",
+        "preview=true",
+        "--base-url",
+        "https://example.test/api",
+      ],
+      {},
+    );
+
+    expect(parsed.method).toBe("POST");
+    expect(parsed.endpoint).toBe("/tools/execute/GITHUB_CREATE_AN_ISSUE");
+    expect(parsed.body).toEqual({ arguments: { title: "demo" } });
+    expect(parsed.query).toEqual([["preview", "true"]]);
+    expect(parsed.baseUrl).toBe("https://example.test/api");
+  });
+
+  test("rejects absolute endpoint URLs so API keys are not routed elsewhere", () => {
+    expect(() => parseComposioArgs(["GET", "https://evil.example/tools"], {})).toThrow(
+      "endpoint must be a Composio API path",
+    );
+  });
+});
+
+describe("runComposioCommand", () => {
+  test("routes request to Composio with x-api-key auth and pretty JSON output", async () => {
+    const out: string[] = [];
+    const fetchMock = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      expect(String(url)).toBe("https://backend.composio.dev/api/v3.1/tools?limit=10");
+      expect(init?.method).toBe("GET");
+      expect((init?.headers as Record<string, string>)["x-api-key"]).toBe("ck_test_secret");
+      return jsonResponse({ ok: true, token: "ck_test_secret" });
+    });
+
+    await runComposioCommand(["GET", "/tools", "--query", "limit=10"], {
+      env: { COMPOSIO_API_KEY: "ck_test_secret" },
+      fetch: fetchMock,
+      log: (message) => out.push(message),
+      error: (message) => out.push(message),
+      exit: () => {
+        throw new Error("should not exit");
+      },
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(out.join("\n")).toContain('"ok": true');
+    expect(out.join("\n")).toContain("[REDACTED:COMPOSIO_API_KEY]");
+    expect(out.join("\n")).not.toContain("ck_test_secret");
+  });
+
+  test("uses org key header when --org is passed", async () => {
+    const fetchMock = mock(async (_url: string | URL | Request, init?: RequestInit) => {
+      expect((init?.headers as Record<string, string>)["x-org-api-key"]).toBe("org_secret_value");
+      expect((init?.headers as Record<string, string>)["x-api-key"]).toBeUndefined();
+      return jsonResponse({ ok: true });
+    });
+
+    await runComposioCommand(["GET", "/org/projects", "--org"], {
+      env: { COMPOSIO_ORG_API_KEY: "org_secret_value" },
+      fetch: fetchMock,
+      log: () => {},
+      error: () => {},
+      exit: () => {
+        throw new Error("should not exit");
+      },
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("exits before fetch when COMPOSIO_API_KEY is missing", async () => {
+    const err: string[] = [];
+    const exit = mock(() => undefined);
+    const fetchMock = mock(async () => jsonResponse({ ok: true }));
+
+    await runComposioCommand(["GET", "/tools"], {
+      env: {},
+      fetch: fetchMock,
+      log: () => {},
+      error: (message) => err.push(message),
+      exit,
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(exit).toHaveBeenCalledWith(1);
+    expect(err.join("\n")).toContain("COMPOSIO_API_KEY is required");
+  });
+});
+
+describe("runXCommand", () => {
+  test("dispatches to composio target", async () => {
+    const fetchMock = mock(async () => jsonResponse({ ok: true }));
+    await runXCommand(["composio", "GET", "/tools"], {
+      env: { COMPOSIO_API_KEY: "ck_test_secret" },
+      fetch: fetchMock,
+      log: () => {},
+      error: () => {},
+      exit: () => {
+        throw new Error("should not exit");
+      },
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/tools/create-metric.ts

@@ -0,0 +1,191 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createMetric, getMetric, getMetricBySlug, getMetricVersions, updateMetric } from "@/be/db";
+import { assertSelectOnlyQuery } from "@/http/db-query";
+import { snapshotMetric } from "@/metrics/version";
+import { createToolRegistrar } from "@/tools/utils";
+import { MetricDefinitionSchema } from "@/types";
+
+function slugify(input: string): string {
+  const slug = input
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "metric";
+}
+
+function getAppBaseUrl(): string {
+  const env = process.env.APP_URL?.trim();
+  if (env) return env.replace(/\/+$/, "");
+  return "http://localhost:5274";
+}
+
+function metricEditCounter(metricId: string): number {
+  const versions = getMetricVersions(metricId);
+  return versions.length > 0 ? versions[0]!.version + 1 : 1;
+}
+
+export const registerCreateMetricTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "create_metric",
+    {
+      title: "Create or update a metric",
+      description:
+        "Stores a config-driven dashboard backed by read-only SQL widget queries. " +
+        "Calls are upsert-by-(agent, slug), mirroring create_page: same slug updates " +
+        "the existing dashboard and snapshots the prior JSON definition.",
+      annotations: { destructiveHint: false },
+      inputSchema: z.object({
+        title: z.string().min(1).describe("Human-readable dashboard title."),
+        slug: z
+          .string()
+          .min(1)
+          .optional()
+          .describe("URL-safe slug. Defaults to the kebab-cased title."),
+        description: z.string().optional().describe("Short description shown in the dashboard."),
+        definition: MetricDefinitionSchema.describe(
+          "Dashboard JSON definition: a list of widgets, each with SELECT/WITH SQL and viz config.",
+        ),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string(),
+        id: z.string(),
+        version: z.number(),
+        app_url: z.string(),
+        success: z.boolean().optional(),
+        message: z.string().optional(),
+      }),
+    },
+    async (input, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        const msg = "Agent ID required. Set the X-Agent-ID header on the MCP request.";
+        return {
+          content: [{ type: "text", text: msg }],
+          structuredContent: {
+            yourAgentId: "",
+            id: "",
+            version: 0,
+            app_url: "",
+            success: false,
+            message: msg,
+          },
+          isError: true,
+        };
+      }
+
+      try {
+        for (const widget of input.definition.widgets) {
+          assertSelectOnlyQuery(widget.query.sql);
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Metric query rejected: ${msg}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            id: "",
+            version: 0,
+            app_url: "",
+            success: false,
+            message: msg,
+          },
+          isError: true,
+        };
+      }
+
+      const slug = input.slug ?? slugify(input.title);
+      const existing = getMetricBySlug(requestInfo.agentId, slug);
+      let id: string;
+
+      if (existing) {
+        try {
+          snapshotMetric(existing.id, requestInfo.agentId);
+        } catch {
+          // Snapshot failure should not block updates.
+        }
+        const updated = updateMetric(existing.id, {
+          title: input.title,
+          description: input.description,
+          definition: input.definition,
+        });
+        if (!updated) {
+          const msg = `Failed to update existing metric ${existing.id}.`;
+          return {
+            content: [{ type: "text", text: msg }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              id: existing.id,
+              version: 0,
+              app_url: "",
+              success: false,
+              message: msg,
+            },
+            isError: true,
+          };
+        }
+        id = updated.id;
+      } else {
+        try {
+          const created = createMetric({
+            agentId: requestInfo.agentId,
+            slug,
+            title: input.title,
+            description: input.description,
+            definition: input.definition,
+          });
+          id = created.id;
+        } catch (err) {
+          const detail = err instanceof Error ? err.message : String(err);
+          const msg = `Failed to create metric: ${detail}`;
+          return {
+            content: [{ type: "text", text: msg }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              id: "",
+              version: 0,
+              app_url: "",
+              success: false,
+              message: msg,
+            },
+            isError: true,
+          };
+        }
+      }
+
+      const fresh = getMetric(id);
+      if (!fresh) {
+        const msg = `Metric ${id} disappeared between write and read.`;
+        return {
+          content: [{ type: "text", text: msg }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            id,
+            version: 0,
+            app_url: "",
+            success: false,
+            message: msg,
+          },
+          isError: true,
+        };
+      }
+
+      const version = metricEditCounter(id);
+      const appUrl = `${getAppBaseUrl()}/usage/metrics`;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Metric "${input.title}" saved (slug=${slug}, version=${version}).\n  App: ${appUrl}`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          id,
+          version,
+          app_url: appUrl,
+        },
+      };
+    },
+  );
+};

package/src/tools/swarm-x.ts

@@ -0,0 +1,116 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { COMPOSIO_HTTP_METHODS, composioArgsFromParts, executeComposioRequest } from "@/x/composio";
+import { createToolRegistrar } from "./utils";
+
+const primitiveQueryValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+
+export const registerSwarmXTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "swarm_x",
+    {
+      title: "Swarm X",
+      description:
+        "Execute an Agent Swarm external command route. v1 supports target='composio' and mirrors `agent-swarm x composio <method> <path>` with the Composio API key injected server-side.",
+      annotations: { openWorldHint: true },
+      inputSchema: z.object({
+        target: z
+          .literal("composio")
+          .default("composio")
+          .describe("External route target. Only 'composio' is supported in v1."),
+        method: z.enum(COMPOSIO_HTTP_METHODS).describe("HTTP method to route to Composio."),
+        path: z
+          .string()
+          .min(1)
+          .describe(
+            "Composio API path relative to the configured base URL, e.g. /tool_router/session.",
+          ),
+        body: z.unknown().optional().describe("Optional JSON request body."),
+        query: z
+          .record(z.string(), primitiveQueryValueSchema)
+          .optional()
+          .describe("Optional query parameters appended to the Composio path."),
+        headers: z
+          .record(z.string(), z.string())
+          .optional()
+          .describe("Optional extra headers. Auth headers are injected by the server."),
+        baseUrl: z.string().url().optional().describe("Optional Composio API base URL override."),
+        useOrgKey: z
+          .boolean()
+          .default(false)
+          .describe(
+            "Use COMPOSIO_ORG_API_KEY/x-org-api-key instead of COMPOSIO_API_KEY/x-api-key.",
+          ),
+        raw: z
+          .boolean()
+          .default(false)
+          .describe("Return raw text instead of JSON-pretty output text."),
+      }),
+      outputSchema: z.object({
+        target: z.literal("composio"),
+        ok: z.boolean(),
+        status: z.number(),
+        statusText: z.string(),
+        method: z.string(),
+        url: z.string(),
+        response: z.unknown(),
+        responseText: z.string(),
+        message: z.string(),
+      }),
+    },
+    async (input) => {
+      let result: Awaited<ReturnType<typeof executeComposioRequest>>;
+      try {
+        result = await executeComposioRequest(
+          composioArgsFromParts({
+            baseUrl: input.baseUrl,
+            body: input.body,
+            endpoint: input.path,
+            headers: input.headers,
+            method: input.method,
+            query: input.query,
+            raw: input.raw,
+            useOrgKey: input.useOrgKey,
+          }),
+        );
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `swarm_x composio: ${message}` }],
+          structuredContent: {
+            target: "composio",
+            ok: false,
+            status: 0,
+            statusText: "Invalid request",
+            method: input.method,
+            url: "",
+            response: null,
+            responseText: "",
+            message,
+          },
+          isError: true,
+        };
+      }
+
+      const message =
+        result.error || result.formattedBody || `HTTP ${result.status} ${result.statusText}`.trim();
+      const structuredContent = {
+        target: "composio" as const,
+        ok: result.ok,
+        status: result.status,
+        statusText: result.statusText,
+        method: result.method,
+        url: result.url,
+        response: result.body,
+        responseText: result.text,
+        message,
+      };
+
+      return {
+        content: [{ type: "text", text: message }],
+        structuredContent,
+        isError: !result.ok,
+      };
+    },
+  );
+};

package/src/tools/tool-config.ts

@@ -122,6 +122,9 @@ export const DEFERRED_TOOLS = new Set([
   // Debug (1)
   "db-query",
 
+  // Metrics (1)
+  "create_metric",
+
   // Approval Requests (1)
   "request-human-input",
 
@@ -168,6 +171,9 @@ export const DEFERRED_TOOLS = new Set([
   "script-delete",
   "script-query-types",
 
+  // External command routes (1)
+  "swarm_x",
+
   // Other (4)
   "cancel-task",
   "inject-learning",

package/src/types.ts

@@ -1017,6 +1017,7 @@ export const ExecutorMetaSchema = z.object({
   nodeId: z.string(),
   workflowId: z.string().uuid(),
   dryRun: z.boolean().default(false),
+  requestedByUserId: z.string().optional(),
 });
 export type ExecutorMeta = z.infer<typeof ExecutorMetaSchema>;
 
@@ -1390,6 +1391,125 @@ export const PageVersionSchema = z.object({
 });
 export type PageVersion = z.infer<typeof PageVersionSchema>;
 
+// ---------------------------------------------------------------------------
+// Metrics
+// ---------------------------------------------------------------------------
+
+const MetricParamSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export type MetricParam = z.infer<typeof MetricParamSchema>;
+const MetricVariableTypeSchema = z.enum(["text", "number", "select"]);
+
+export const MetricFormatSchema = z.enum(["number", "integer", "currency", "percent", "duration"]);
+export type MetricFormat = z.infer<typeof MetricFormatSchema>;
+
+export const MetricVisualizationSchema = z.enum([
+  "stat",
+  "table",
+  "bar",
+  "line",
+  "multi-bar",
+  "multi-line",
+]);
+export type MetricVisualization = z.infer<typeof MetricVisualizationSchema>;
+
+const MetricQuerySchema = z.object({
+  sql: z.string().min(1).max(10_000),
+  params: z.array(MetricParamSchema).optional(),
+  maxRows: z.number().int().min(1).max(500).optional(),
+});
+
+export const MetricVariableSchema = z.object({
+  key: z
+    .string()
+    .min(1)
+    .regex(/^[a-zA-Z][a-zA-Z0-9_]*$/),
+  label: z.string().min(1).optional(),
+  type: MetricVariableTypeSchema.default("text"),
+  defaultValue: MetricParamSchema.optional(),
+  options: z
+    .array(
+      z.object({
+        label: z.string().min(1),
+        value: MetricParamSchema,
+      }),
+    )
+    .optional(),
+});
+export type MetricVariable = z.infer<typeof MetricVariableSchema>;
+
+export const MetricVizConfigSchema = z.object({
+  type: MetricVisualizationSchema,
+  x: z.string().optional(),
+  y: z.string().optional(),
+  series: z.array(z.string()).optional(),
+  label: z.string().optional(),
+  value: z.string().optional(),
+  columns: z
+    .array(
+      z.object({
+        key: z.string(),
+        label: z.string().optional(),
+        format: MetricFormatSchema.optional(),
+      }),
+    )
+    .optional(),
+  format: MetricFormatSchema.optional(),
+});
+export type MetricVizConfig = z.infer<typeof MetricVizConfigSchema>;
+
+export const MetricWidgetSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string().optional(),
+  query: MetricQuerySchema,
+  viz: MetricVizConfigSchema,
+});
+export type MetricWidget = z.infer<typeof MetricWidgetSchema>;
+
+export const MetricDefinitionSchema = z.object({
+  version: z.literal(1),
+  widgets: z.array(MetricWidgetSchema).min(1).max(24),
+  variables: z.array(MetricVariableSchema).max(12).optional(),
+  layout: z
+    .object({
+      columns: z.number().int().min(1).max(4).optional(),
+    })
+    .optional(),
+  refreshSeconds: z.number().int().min(5).max(3600).optional(),
+});
+export type MetricDefinition = z.infer<typeof MetricDefinitionSchema>;
+
+export const MetricSnapshotSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  definition: MetricDefinitionSchema,
+});
+export type MetricSnapshot = z.infer<typeof MetricSnapshotSchema>;
+
+export const MetricSchema = z.object({
+  id: z.string(),
+  agentId: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  definition: MetricDefinitionSchema,
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Metric = z.infer<typeof MetricSchema>;
+
+export type MetricSummary = Omit<Metric, "definition">;
+
+export const MetricVersionSchema = z.object({
+  id: z.string(),
+  metricId: z.string(),
+  version: z.number().int().min(1),
+  snapshot: MetricSnapshotSchema,
+  changedByAgentId: z.string().optional(),
+  createdAt: z.string(),
+});
+export type MetricVersion = z.infer<typeof MetricVersionSchema>;
+
 // --- Workflow Run ---
 
 export const WorkflowRunStatusSchema = z.enum([

package/src/utils/request-auth-context.ts

@@ -0,0 +1,28 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { IncomingMessage } from "node:http";
+import type { User } from "../types";
+
+export type HttpRequestAuth =
+  | { kind: "operator"; fingerprint: string }
+  | { kind: "user"; userId: string; user: User };
+
+const requestAuth = new WeakMap<IncomingMessage, HttpRequestAuth | null>();
+const authStorage = new AsyncLocalStorage<HttpRequestAuth | null>();
+
+export function setRequestAuth(req: IncomingMessage, auth: HttpRequestAuth | null): void {
+  requestAuth.set(req, auth);
+  authStorage.enterWith(auth);
+}
+
+export function getRequestAuth(req: IncomingMessage): HttpRequestAuth | null {
+  return requestAuth.get(req) ?? null;
+}
+
+export function getCurrentRequestAuth(): HttpRequestAuth | null {
+  return authStorage.getStore() ?? null;
+}
+
+export function getCurrentRequestUserId(): string | undefined {
+  const auth = getCurrentRequestAuth();
+  return auth?.kind === "user" ? auth.userId : undefined;
+}

package/src/utils/skills-refresh.ts

@@ -28,7 +28,7 @@ export async function refreshSkillsIfChanged(
   ctx: SkillsRefreshContext,
   lastHashRef: { current: string | null },
 ): Promise<SkillsRefreshResult> {
-  const { apiUrl, swarmUrl, apiKey, agentId, role } = ctx;
+  const { apiUrl, apiKey, agentId, role } = ctx;
   const authHeaders: Record<string, string> = { "X-Agent-ID": agentId };
   if (apiKey) authHeaders.Authorization = `Bearer ${apiKey}`;
 
@@ -83,7 +83,7 @@ export async function refreshSkillsIfChanged(
       "X-Agent-ID": agentId,
     };
     if (apiKey) syncHeaders.Authorization = `Bearer ${apiKey}`;
-    const syncRes = await fetch(`${swarmUrl}/api/skills/sync-filesystem`, {
+    const syncRes = await fetch(`${apiUrl}/api/skills/sync-filesystem`, {
       method: "POST",
       headers: syncHeaders,
     });