@desplega.ai/agent-swarm 1.87.0 → 1.89.0

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/skills/skill-delete.ts

@@ -3,6 +3,9 @@ import * as z from "zod";
 import { deleteSkill, getAgentById, getSkillById } from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
 
+const SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE =
+  "This skill is system-managed and cannot be edited from the UI; it is re-seeded on each start. Fork it under a new name to customize.";
+
 export const registerSkillDeleteTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "skill-delete",
@@ -51,6 +54,17 @@ export const registerSkillDeleteTool = (server: McpServer) => {
         };
       }
 
+      if (existing.systemDefault) {
+        return {
+          content: [{ type: "text", text: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE,
+          },
+        };
+      }
+
       const deleted = deleteSkill(args.skillId);
       return {
         content: [

package/src/tools/skills/skill-update.ts

@@ -4,6 +4,9 @@ import { getAgentById, getSkillById, updateSkill } from "@/be/db";
 import { parseSkillContent } from "@/be/skill-parser";
 import { createToolRegistrar } from "@/tools/utils";
 
+const SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE =
+  "This skill is system-managed and cannot be edited from the UI; it is re-seeded on each start. Fork it under a new name to customize.";
+
 export const registerSkillUpdateTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "skill-update",
@@ -77,6 +80,17 @@ export const registerSkillUpdateTool = (server: McpServer) => {
           };
         }
 
+        if (existing.systemDefault && (args.content !== undefined || args.scope !== undefined)) {
+          return {
+            content: [{ type: "text", text: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE,
+            },
+          };
+        }
+
         const updates: Parameters<typeof updateSkill>[1] = {};
 
         if (args.content !== undefined) {

package/src/tools/store-progress.ts

@@ -16,6 +16,7 @@ import {
 import { getEmbeddingProvider, getMemoryStore } from "@/be/memory";
 import { getRetrievalsForTask } from "@/be/memory/raters/retrieval";
 import { runServerRaters } from "@/be/memory/raters/run-server-raters";
+import { shouldPersistTaskCompletionMemory } from "@/memory/automatic-task-gate";
 import { createWorkerTaskFollowUp } from "@/tasks/worker-follow-up";
 import { createToolRegistrar } from "@/tools/utils";
 import { AgentTaskSchema, AttachmentInputSchema, isTerminalTaskStatus } from "@/types";
@@ -56,6 +57,12 @@ export const registerStoreProgressTool = (server: McpServer) => {
           .describe(
             "Pointer-based artifacts produced by this step — agent-fs path, URL, shared-fs path, or swarm Page. No inline file data; upload to agent-fs first and attach by path. May be sent on any call (progress or completion) and accumulates across calls; duplicates are de-duped by sha256 (when present) or by (kind, pointer, name).",
           ),
+        persistMemory: z
+          .boolean()
+          .optional()
+          .describe(
+            "Opt in to task_completion memory persistence for automatic/recurring tasks. Manual tasks are persisted by default; scheduled, system, heartbeat/boot-triage, monitor, and digest tasks are skipped unless this is true.",
+          ),
         // Phase 11: `costData` removed. The harness adapter is the sole
         // writer of `session_costs` (see POST /api/session-costs in the
         // runner). If a payload still includes the field, Zod's
@@ -75,7 +82,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
       }),
     },
     async (
-      { taskId, progress, status, output, failureReason, attachments },
+      { taskId, progress, status, output, failureReason, attachments, persistMemory },
       requestInfo,
       _meta,
     ) => {
@@ -320,14 +327,19 @@ export const registerStoreProgressTool = (server: McpServer) => {
 
       const result = txn();
 
+      const shouldRunTerminalSideEffects =
+        (status === "completed" || status === "failed") &&
+        result.success &&
+        result.task &&
+        !("wasNoOp" in result && result.wasNoOp);
+
       // Index completed and failed tasks as memory (async, non-blocking).
       // Skip on no-op (idempotent re-call on terminal task) to avoid duplicate
       // memory entries / vector index pollution.
+      // Automatic/recurring tasks are noisy by default; require explicit opt-in.
       if (
-        (status === "completed" || status === "failed") &&
-        result.success &&
-        result.task &&
-        !("wasNoOp" in result && result.wasNoOp)
+        shouldRunTerminalSideEffects &&
+        shouldPersistTaskCompletionMemory(result.task, persistMemory)
       ) {
         (async () => {
           try {
@@ -384,7 +396,9 @@ export const registerStoreProgressTool = (server: McpServer) => {
             // Non-blocking — task completion memory failure should not affect task status
           }
         })();
+      }
 
+      if (shouldRunTerminalSideEffects) {
         // Memory rater v1.5 — fire server-side raters on task completion.
         // Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-2.md §5
         //

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([
@@ -1600,6 +1720,7 @@ export const SkillSchema = z.object({
   userInvocable: z.boolean(),
   version: z.number(),
   isEnabled: z.boolean(),
+  systemDefault: z.boolean(),
   createdAt: z.string(),
   lastUpdatedAt: z.string(),
   lastFetchedAt: z.string().nullable(),

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,
     });