@desplega.ai/agent-swarm 1.88.0 → 1.89.0

package/src/http/core.ts

@@ -15,7 +15,9 @@ import { initJira, resetJira } from "../jira";
 import { initLinear, resetLinear } from "../linear";
 import { startSlackApp, stopSlackApp } from "../slack";
 import type { AgentStatus } from "../types";
+import { setRequestAuth } from "../utils/request-auth-context";
 import { refreshSecretScrubberCache } from "../utils/secret-scrubber";
+import { resolveHttpRequestAuth } from "./auth";
 import { generateOpenApiSpec, SCALAR_HTML } from "./openapi";
 import { isPublicRoute } from "./route-def";
 import { agentWithCapacity, getPathSegments, parseQueryParams } from "./utils";
@@ -234,25 +236,27 @@ export async function handleCore(
     return true;
   }
 
-  // API-key authentication (if API_KEY is configured). Routes that opt out via
+  // API-key authentication. Routes that opt out via
   // `route({ auth: { apiKey: false } })` — webhooks, OAuth provider callbacks,
   // etc. — are skipped based on the central `routeRegistry`. Unknown paths
-  // fall through to the bearer check (fail-closed).
-  if (apiKey) {
-    const pathSegments = getPathSegments(req.url || "");
-    const isUserMcpRoute = req.url === "/mcp-user";
-    // `/mcp-user` runs its own `aswt_`-token auth in `handleMcpUser`; the swarm
-    // API key must not gate it.
-    if (!isUserMcpRoute && !isPublicRoute(req.method, pathSegments)) {
-      const authHeader = req.headers.authorization;
-      const providedKey = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
-
-      if (providedKey !== apiKey) {
-        res.writeHead(401, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Unauthorized" }));
-        return true;
-      }
+  // fall through to the bearer check (fail-closed). Normal API calls may use
+  // either the global swarm key or an active user-bound `aswt_` token.
+  const pathSegments = getPathSegments(req.url || "");
+  const isUserMcpRoute = req.url === "/mcp-user";
+  // `/mcp-user` runs its own `aswt_`-token auth in `handleMcpUser`; the swarm
+  // API key must not gate it.
+  if (isUserMcpRoute || isPublicRoute(req.method, pathSegments)) {
+    setRequestAuth(req, null);
+  } else {
+    const auth = resolveHttpRequestAuth(req, apiKey);
+
+    if (!auth) {
+      setRequestAuth(req, null);
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Unauthorized" }));
+      return true;
     }
+    setRequestAuth(req, auth);
   }
 
   // POST /internal/reload-config — re-read swarm_config into process.env and re-init integrations

package/src/http/db-query.ts

@@ -11,6 +11,25 @@ export interface DbQueryResult {
   total: number;
 }
 
+function stripTrailingSemicolon(sql: string): string {
+  return sql.trim().replace(/;\s*$/, "").trim();
+}
+
+function assertSingleStatement(sql: string): void {
+  const stripped = stripTrailingSemicolon(sql);
+  if (stripped.includes(";")) {
+    throw new Error("Only one SQL statement is allowed");
+  }
+}
+
+export function assertSelectOnlyQuery(sql: string): void {
+  assertSingleStatement(sql);
+  const normalized = stripTrailingSemicolon(sql).toLowerCase();
+  if (!normalized.startsWith("select ") && !normalized.startsWith("with ")) {
+    throw new Error("Metric queries must start with SELECT or WITH");
+  }
+}
+
 /**
  * Execute a read-only SQL query against the swarm database.
  * Detects write statements via bun:sqlite's columnNames (empty for INSERT/UPDATE/DELETE/DROP).
@@ -20,6 +39,7 @@ export function executeReadOnlyQuery(
   params: unknown[] = [],
   maxRows?: number,
 ): DbQueryResult {
+  assertSingleStatement(sql);
   const stmt = getDb().prepare(sql);
 
   // bun:sqlite: columnNames is empty for write statements, populated for SELECT/PRAGMA/EXPLAIN

package/src/http/index.ts

@@ -46,6 +46,7 @@ import { handleMcpOAuth, startMcpOAuthPendingGc, stopMcpOAuthPendingGc } from ".
 import { handleMcpServers } from "./mcp-servers";
 import { handleMcpUser } from "./mcp-user";
 import { handleMemory } from "./memory";
+import { handleMetrics } from "./metrics";
 import { handlePageProxy } from "./page-proxy";
 import { handlePages } from "./pages";
 import { handlePagesPublic } from "./pages-public";
@@ -229,6 +230,7 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleIntegrations(req, res, pathSegments),
         () => handlePromptTemplates(req, res, pathSegments, queryParams),
         () => handleDbQuery(req, res, pathSegments, queryParams),
+        () => handleMetrics(req, res, pathSegments, queryParams, myAgentId),
         () => handleRepos(req, res, pathSegments, queryParams),
         () => handleSkills(req, res, pathSegments, queryParams, myAgentId),
         () => handleScripts(req, res, pathSegments, queryParams, myAgentId),

package/src/http/metrics.ts

@@ -0,0 +1,447 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import {
+  countAllMetrics,
+  countMetricsByAgent,
+  createMetric,
+  deleteMetric,
+  getMetric,
+  getMetricVersion,
+  getMetricVersions,
+  listAllMetrics,
+  listMetricsByAgent,
+  updateMetric,
+} from "../be/db";
+import { snapshotMetric } from "../metrics/version";
+import {
+  type Metric,
+  MetricDefinitionSchema,
+  type MetricParam,
+  type MetricSummary,
+  type MetricVariable,
+  MetricVersionSchema,
+  type MetricWidget,
+} from "../types";
+import { assertSelectOnlyQuery, executeReadOnlyQuery } from "./db-query";
+import { route } from "./route-def";
+import { json, jsonError } from "./utils";
+
+const DEFAULT_METRIC_MAX_ROWS = 100;
+const HARD_METRIC_MAX_ROWS = 500;
+const VARIABLE_TOKEN_RE = /^\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}$/;
+const MetricRunBodySchema = z
+  .object({
+    variables: z
+      .record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]))
+      .optional(),
+  })
+  .optional();
+
+function slugify(input: string): string {
+  const slug = input
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "metric";
+}
+
+function validateMetricDefinition(definition: unknown) {
+  const parsed = MetricDefinitionSchema.parse(definition);
+  for (const widget of parsed.widgets) {
+    assertSelectOnlyQuery(widget.query.sql);
+  }
+  return parsed;
+}
+
+function coerceVariableValue(variable: MetricVariable, raw: unknown): MetricParam {
+  if (raw == null || raw === "") {
+    return variable.defaultValue ?? null;
+  }
+  if (variable.type === "number") {
+    const numeric = typeof raw === "number" ? raw : Number(raw);
+    if (!Number.isFinite(numeric)) {
+      throw new Error(`Metric variable "${variable.key}" must be a number`);
+    }
+    return numeric;
+  }
+  if (typeof raw === "boolean" || typeof raw === "number" || typeof raw === "string") {
+    return raw;
+  }
+  return String(raw);
+}
+
+function resolveMetricVariables(metric: Metric, provided: Record<string, unknown>) {
+  const values: Record<string, MetricParam> = {};
+  for (const variable of metric.definition.variables ?? []) {
+    const value = coerceVariableValue(variable, provided[variable.key]);
+    if (variable.options?.length) {
+      const allowed = variable.options.some((option) => option.value === value);
+      if (!allowed) {
+        throw new Error(`Metric variable "${variable.key}" must match one of its options`);
+      }
+    }
+    values[variable.key] = value;
+  }
+  return values;
+}
+
+function resolveWidgetParams(
+  widget: MetricWidget,
+  variables: Record<string, MetricParam>,
+): MetricParam[] {
+  return (widget.query.params ?? []).map((param) => {
+    if (typeof param !== "string") return param;
+    const match = VARIABLE_TOKEN_RE.exec(param);
+    if (!match) return param;
+    const key = match[1]!;
+    if (!(key in variables)) {
+      throw new Error(`Metric variable "${key}" is not defined`);
+    }
+    return variables[key] ?? null;
+  });
+}
+
+function runMetricWidget(widget: MetricWidget, variables: Record<string, MetricParam>) {
+  assertSelectOnlyQuery(widget.query.sql);
+  const requestedRows = widget.query.maxRows ?? DEFAULT_METRIC_MAX_ROWS;
+  const maxRows = Math.min(requestedRows, HARD_METRIC_MAX_ROWS);
+  const result = executeReadOnlyQuery(
+    widget.query.sql,
+    resolveWidgetParams(widget, variables),
+    maxRows,
+  );
+  return {
+    widget,
+    result: {
+      ...result,
+      rows: result.rows.map((row) =>
+        Object.fromEntries(result.columns.map((column, index) => [column, row[index]])),
+      ),
+      truncated: result.total > result.rows.length,
+      maxRows,
+    },
+  };
+}
+
+function runMetric(metric: Metric, providedVariables: Record<string, unknown> = {}) {
+  const variables = resolveMetricVariables(metric, providedVariables);
+  const widgets = metric.definition.widgets.map((widget) => runMetricWidget(widget, variables));
+  return {
+    metric,
+    variables,
+    widgets,
+    // Kept as the first widget result for older callers during the PR cycle.
+    result: widgets[0]?.result,
+  };
+}
+
+const metricDefinitionBody = z.object({
+  slug: z.string().min(1).optional(),
+  title: z.string().min(1),
+  description: z.string().nullable().optional(),
+  definition: MetricDefinitionSchema,
+});
+
+const createMetricRoute = route({
+  method: "post",
+  path: "/api/metrics/definitions",
+  pattern: ["api", "metrics", "definitions"],
+  summary: "Create a metric definition",
+  tags: ["Metrics"],
+  body: metricDefinitionBody,
+  responses: {
+    201: { description: "Metric created" },
+    400: { description: "Invalid metric definition" },
+    409: { description: "Slug already exists for this agent" },
+  },
+});
+
+const listMetricsRoute = route({
+  method: "get",
+  path: "/api/metrics/definitions",
+  pattern: ["api", "metrics", "definitions"],
+  summary: "List metric definitions",
+  tags: ["Metrics"],
+  query: z.object({
+    agentId: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(500).optional(),
+    offset: z.coerce.number().int().min(0).optional(),
+    fields: z.enum(["full", "slim"]).optional(),
+  }),
+  responses: {
+    200: { description: "Metric definitions" },
+  },
+});
+
+const getMetricRoute = route({
+  method: "get",
+  path: "/api/metrics/definitions/{id}",
+  pattern: ["api", "metrics", "definitions", null],
+  summary: "Get a metric definition",
+  tags: ["Metrics"],
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "Metric definition" },
+    404: { description: "Metric not found" },
+  },
+});
+
+const updateMetricRoute = route({
+  method: "put",
+  path: "/api/metrics/definitions/{id}",
+  pattern: ["api", "metrics", "definitions", null],
+  summary: "Update a metric definition",
+  tags: ["Metrics"],
+  params: z.object({ id: z.string() }),
+  body: metricDefinitionBody.partial(),
+  responses: {
+    200: { description: "Metric updated" },
+    404: { description: "Metric not found" },
+  },
+});
+
+const deleteMetricRoute = route({
+  method: "delete",
+  path: "/api/metrics/definitions/{id}",
+  pattern: ["api", "metrics", "definitions", null],
+  summary: "Delete a metric definition",
+  tags: ["Metrics"],
+  params: z.object({ id: z.string() }),
+  responses: {
+    204: { description: "Metric deleted" },
+    404: { description: "Metric not found" },
+  },
+});
+
+const runMetricRoute = route({
+  method: "post",
+  path: "/api/metrics/definitions/{id}/run",
+  pattern: ["api", "metrics", "definitions", null, "run"],
+  summary: "Run a metric definition",
+  tags: ["Metrics"],
+  params: z.object({ id: z.string() }),
+  body: MetricRunBodySchema,
+  responses: {
+    200: { description: "Metric result" },
+    400: { description: "Invalid or disallowed query" },
+    404: { description: "Metric not found" },
+  },
+});
+
+const listMetricVersionsRoute = route({
+  method: "get",
+  path: "/api/metrics/definitions/{id}/versions",
+  pattern: ["api", "metrics", "definitions", null, "versions"],
+  summary: "List metric definition versions",
+  tags: ["Metrics"],
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "Metric version list" },
+    404: { description: "Metric not found" },
+  },
+});
+
+const getMetricVersionRoute = route({
+  method: "get",
+  path: "/api/metrics/definitions/{id}/versions/{version}",
+  pattern: ["api", "metrics", "definitions", null, "versions", null],
+  summary: "Get a metric definition version",
+  tags: ["Metrics"],
+  params: z.object({ id: z.string(), version: z.coerce.number().int().min(1) }),
+  responses: {
+    200: { description: "Metric version" },
+    404: { description: "Metric or version not found" },
+  },
+});
+
+const metricSchemaRoute = route({
+  method: "get",
+  path: "/api/metrics/schema",
+  pattern: ["api", "metrics", "schema"],
+  summary: "Get the metric definition JSON Schema",
+  tags: ["Metrics"],
+  responses: {
+    200: { description: "Metric definition JSON Schema" },
+  },
+});
+
+function metricEditCounter(metricId: string): number {
+  const versions = getMetricVersions(metricId);
+  return versions.length > 0 ? versions[0]!.version + 1 : 1;
+}
+
+export async function handleMetrics(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+  myAgentId: string | undefined,
+): Promise<boolean> {
+  if (metricSchemaRoute.match(req.method, pathSegments)) {
+    json(res, { schema: z.toJSONSchema(MetricDefinitionSchema, { target: "draft-7" }) });
+    return true;
+  }
+
+  if (createMetricRoute.match(req.method, pathSegments)) {
+    const parsed = await createMetricRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const ownerAgentId = myAgentId ?? "ui";
+
+    try {
+      const definition = validateMetricDefinition(parsed.body.definition);
+      const slug = parsed.body.slug ?? slugify(parsed.body.title);
+      const metric = createMetric({
+        agentId: ownerAgentId,
+        slug,
+        title: parsed.body.title,
+        description: parsed.body.description ?? undefined,
+        definition,
+      });
+      json(res, { id: metric.id, version: 1 }, 201);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("UNIQUE")) {
+        const slug = parsed.body.slug ?? slugify(parsed.body.title);
+        jsonError(res, `Metric with slug "${slug}" already exists for this agent`, 409);
+        return true;
+      }
+      jsonError(res, msg);
+    }
+    return true;
+  }
+
+  if (listMetricsRoute.match(req.method, pathSegments)) {
+    const parsed = await listMetricsRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const limit = parsed.query.limit ?? 100;
+    const offset = parsed.query.offset ?? 0;
+    const full = parsed.query.fields === "full";
+    let metrics: Array<Metric | MetricSummary>;
+    let total: number;
+    if (parsed.query.agentId) {
+      metrics = full
+        ? listMetricsByAgent(parsed.query.agentId, limit, offset)
+        : listMetricsByAgent(parsed.query.agentId, limit, offset, { slim: true });
+      total = countMetricsByAgent(parsed.query.agentId);
+    } else {
+      metrics = full
+        ? listAllMetrics(limit, offset)
+        : listAllMetrics(limit, offset, { slim: true });
+      total = countAllMetrics();
+    }
+    json(res, { metrics, total, limit, offset });
+    return true;
+  }
+
+  if (runMetricRoute.match(req.method, pathSegments)) {
+    const parsed = await runMetricRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const metric = getMetric(parsed.params.id);
+    if (!metric) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    try {
+      json(res, runMetric(metric, parsed.body?.variables ?? {}));
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : String(err));
+    }
+    return true;
+  }
+
+  if (getMetricVersionRoute.match(req.method, pathSegments)) {
+    const parsed = await getMetricVersionRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!getMetric(parsed.params.id)) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    const version = getMetricVersion(parsed.params.id, parsed.params.version);
+    if (!version) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    json(res, MetricVersionSchema.parse(version));
+    return true;
+  }
+
+  if (listMetricVersionsRoute.match(req.method, pathSegments)) {
+    const parsed = await listMetricVersionsRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!getMetric(parsed.params.id)) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    json(res, { versions: getMetricVersions(parsed.params.id) });
+    return true;
+  }
+
+  if (getMetricRoute.match(req.method, pathSegments)) {
+    const parsed = await getMetricRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const metric = getMetric(parsed.params.id);
+    if (!metric) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    json(res, metric);
+    return true;
+  }
+
+  if (updateMetricRoute.match(req.method, pathSegments)) {
+    const parsed = await updateMetricRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!getMetric(parsed.params.id)) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    try {
+      const definition =
+        parsed.body.definition !== undefined
+          ? validateMetricDefinition(parsed.body.definition)
+          : undefined;
+      try {
+        snapshotMetric(parsed.params.id, myAgentId);
+      } catch {
+        // Snapshot failures should not block edits, matching Pages.
+      }
+      const updated = updateMetric(parsed.params.id, {
+        title: parsed.body.title,
+        description: parsed.body.description ?? undefined,
+        definition,
+        slug: parsed.body.slug,
+      });
+      if (!updated) {
+        res.writeHead(404);
+        res.end();
+        return true;
+      }
+      json(res, { id: updated.id, version: metricEditCounter(updated.id) });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : String(err));
+    }
+    return true;
+  }
+
+  if (deleteMetricRoute.match(req.method, pathSegments)) {
+    const parsed = await deleteMetricRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!deleteMetric(parsed.params.id)) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    res.writeHead(204);
+    res.end();
+    return true;
+  }
+
+  return false;
+}

package/src/http/operator-actor.ts

@@ -17,6 +17,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { fingerprintApiKey, type IdentityActor } from "../be/users";
 import { getApiKey } from "../utils/api-key";
+import { getRequestAuth } from "../utils/request-auth-context";
 import { jsonError } from "./utils";
 
 /**
@@ -40,6 +41,14 @@ function extractBearer(req: IncomingMessage): string | null {
  * the request when this returns null.
  */
 export function getOperatorActor(req: IncomingMessage, res: ServerResponse): IdentityActor | null {
+  const auth = getRequestAuth(req);
+  if (auth?.kind === "user") {
+    return { kind: "user", id: auth.userId };
+  }
+  if (auth?.kind === "operator") {
+    return { kind: "operator", id: auth.fingerprint };
+  }
+
   const rawKey = extractBearer(req);
   const swarmKey = getApiKey();
 

package/src/http/poll.ts

@@ -86,6 +86,10 @@ const pollTriggers = route({
 const CHANNEL_ACTIVITY_INTERVAL_MS = 60_000; // Check at most once per 60s
 let lastChannelActivityCheckAt = 0;
 
+function getRequesterNotes(notes: string | undefined): string | undefined {
+  return typeof notes === "string" && notes.trim().length > 0 ? notes : undefined;
+}
+
 // ─── Cursor Commit Endpoint ─────────────────────────────────────────────────
 
 const commitCursorsRoute = route({
@@ -256,6 +260,7 @@ export async function handlePoll(
             const requestedByUser = pendingTask.requestedByUserId
               ? getUserById(pendingTask.requestedByUserId)
               : undefined;
+            const requestedByNotes = getRequesterNotes(requestedByUser?.notes);
 
             return {
               trigger: {
@@ -263,7 +268,12 @@ export async function handlePoll(
                 taskId: pendingTask.id,
                 task: { ...pendingTask, status: "in_progress" },
                 ...(requestedByUser && {
-                  requestedBy: { name: requestedByUser.name, email: requestedByUser.email },
+                  requestedBy: {
+                    name: requestedByUser.name,
+                    email: requestedByUser.email,
+                    role: requestedByUser.role,
+                    notes: requestedByNotes,
+                  },
                 }),
               },
             };

package/src/http/tasks.ts

@@ -34,6 +34,7 @@ import {
   ProviderNameSchema,
   ResumeReasonSchema,
 } from "../types";
+import { getRequestAuth } from "../utils/request-auth-context";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
@@ -354,7 +355,9 @@ export async function handleTasks(
     // Tolerant `requestedByUserId`: prevent the deleted-user race from
     // becoming a 500 — if the referenced user doesn't exist, log and drop
     // the field rather than letting the FK fail at INSERT.
-    let requestedByUserId = parsed.body.requestedByUserId || undefined;
+    const auth = getRequestAuth(req);
+    let requestedByUserId =
+      auth?.kind === "user" ? auth.userId : parsed.body.requestedByUserId || undefined;
     if (requestedByUserId && !getUserById(requestedByUserId)) {
       console.warn(
         `[tasks] requestedByUserId ${requestedByUserId} does not exist — coercing to NULL`,

package/src/http/workflows.ts

@@ -21,6 +21,7 @@ import {
   WorkflowPatchSchema,
   WorkflowRunStatusSchema,
 } from "../types";
+import { getRequestAuth } from "../utils/request-auth-context";
 import { getExecutorRegistry, startWorkflowExecution } from "../workflows";
 import { applyDefinitionPatch, generateEdges, validateDefinition } from "../workflows/definition";
 import { TriggerSchemaError } from "../workflows/engine";
@@ -645,10 +646,13 @@ export async function handleWorkflows(
       return true;
     }
     const body = await parseBody<Record<string, unknown>>(req);
+    const auth = getRequestAuth(req);
 
     let runId: string;
     try {
-      runId = await startWorkflowExecution(workflow, body, getExecutorRegistry());
+      runId = await startWorkflowExecution(workflow, body, getExecutorRegistry(), {
+        requestedByUserId: auth?.kind === "user" ? auth.userId : undefined,
+      });
     } catch (err) {
       if (err instanceof TriggerSchemaError) {
         triggerSchemaErrorResponse(res, err.message, err.validationErrors);

package/src/metrics/version.ts

@@ -0,0 +1,26 @@
+import { createMetricVersion, getMetric, getMetricVersions } from "../be/db";
+import type { MetricSnapshot, MetricVersion } from "../types";
+
+export function snapshotMetric(metricId: string, changedByAgentId?: string): MetricVersion {
+  const metric = getMetric(metricId);
+  if (!metric) {
+    throw new Error(`Metric ${metricId} not found — cannot create snapshot`);
+  }
+
+  const existingVersions = getMetricVersions(metricId);
+  const maxVersion = existingVersions.length > 0 ? existingVersions[0]!.version : 0;
+  const nextVersion = maxVersion + 1;
+
+  const snapshot: MetricSnapshot = {
+    title: metric.title,
+    description: metric.description,
+    definition: metric.definition,
+  };
+
+  return createMetricVersion({
+    metricId,
+    version: nextVersion,
+    snapshot,
+    changedByAgentId,
+  });
+}