@desplega.ai/agent-swarm 2.3.0 → 2.4.1

package/src/telemetry-identity.ts

@@ -4,6 +4,8 @@
  *
  * - `context.org_domain`: the email DOMAIN of the org's admin (never the email)
  * - `context.user_role`: `admin` when the user's grants include everything, else `member`
+ * - `context.user_function`: a canonical job function from `users.metadata.jobFunction`
+ *   (not `users.role`: the dashboard reads an empty or `admin` role as admin-like)
  *
  * This file must not import `./be/db` (`be/db.ts` imports the trigger module
  * that imports this one). It reads through the DB client and lazy-imports RBAC.
@@ -11,26 +13,36 @@
 import { getDbClient } from "./be/db/runtime";
 import { setTelemetryOrgDomain } from "./telemetry";
 import { emailDomain, type TelemetryUserRole } from "./telemetry-context";
+import { USER_FUNCTIONS } from "./utils/company-profile";
 
 const ROLE_TTL_MS = 60 * 60_000;
 const ROLE_CACHE_LIMIT = 1_000;
 const DOMAIN_RECOMPUTE_DEBOUNCE_MS = 2_000;
 
-const roleCache = new Map<string, { role: TelemetryUserRole; at: number }>();
+interface UserRoleEntry {
+  role: TelemetryUserRole;
+  userFunction?: (typeof USER_FUNCTIONS)[number];
+  at: number;
+}
+
+const roleCache = new Map<string, UserRoleEntry>();
 const roleLoads = new Map<string, Promise<TelemetryUserRole | undefined>>();
 
-async function loadUserRole(userId: string): Promise<TelemetryUserRole | undefined> {
+async function loadUserRole(userId: string): Promise<UserRoleEntry | undefined> {
   try {
     // Lazy: be/rbac-roles imports be/db, which (transitively) imports this file.
     const { getUserGrant } = await import("./be/rbac-roles");
     const grant = await getUserGrant(userId);
     const role: TelemetryUserRole = grant.grantsAll ? "admin" : "member";
-    if (roleCache.size >= ROLE_CACHE_LIMIT) {
-      const oldest = roleCache.keys().next().value;
-      if (oldest !== undefined) roleCache.delete(oldest);
-    }
-    roleCache.set(userId, { role, at: Date.now() });
-    return role;
+    const user = await getDbClient().get<{ jobFunction: string | null }>(
+      "SELECT json_extract(metadata, '$.jobFunction') AS jobFunction FROM users WHERE id = ? AND json_valid(metadata)",
+      [userId],
+    );
+    return {
+      role,
+      userFunction: USER_FUNCTIONS.find((value) => value === user?.jobFunction),
+      at: Date.now(),
+    };
   } catch {
     return undefined;
   }
@@ -42,7 +54,20 @@ export function primeUserRole(userId: string): Promise<TelemetryUserRole | undef
   if (hit && Date.now() - hit.at < ROLE_TTL_MS) return Promise.resolve(hit.role);
   let load = roleLoads.get(userId);
   if (!load) {
-    load = loadUserRole(userId).finally(() => roleLoads.delete(userId));
+    load = loadUserRole(userId)
+      .then((entry) => {
+        if (entry && roleLoads.get(userId) === load) {
+          if (roleCache.size >= ROLE_CACHE_LIMIT) {
+            const oldest = roleCache.keys().next().value;
+            if (oldest !== undefined) roleCache.delete(oldest);
+          }
+          roleCache.set(userId, entry);
+        }
+        return entry?.role;
+      })
+      .finally(() => {
+        if (roleLoads.get(userId) === load) roleLoads.delete(userId);
+      });
     roleLoads.set(userId, load);
   }
   return load;
@@ -59,6 +84,19 @@ export function cachedUserRole(userId: string): TelemetryUserRole | undefined {
   return hit?.role;
 }
 
+/** Resolve the job function from the same cache and lookup as the RBAC role. */
+export function cachedUserFunction(userId: string): UserRoleEntry["userFunction"] {
+  const hit = roleCache.get(userId);
+  if (!hit || Date.now() - hit.at >= ROLE_TTL_MS) void primeUserRole(userId);
+  return hit?.userFunction;
+}
+
+/** Invalidate after a user mutation commits, including any lookup already in progress. */
+export function invalidateTelemetryUserRole(userId: string): void {
+  roleCache.delete(userId);
+  roleLoads.delete(userId);
+}
+
 /**
  * The email domain of the org's earliest-created active admin, falling back to
  * the earliest active user with an email. A candidate whose address has no

package/src/telemetry-snapshot.ts

@@ -9,9 +9,15 @@
  */
 
 import { getDbClient } from "./be/db/runtime";
-import { isTelemetryReady, setTelemetryRoleResolver, telemetry } from "./telemetry";
+import {
+  isTelemetryReady,
+  setTelemetryFunctionResolver,
+  setTelemetryRoleResolver,
+  telemetry,
+} from "./telemetry";
 import type { PropsFor } from "./telemetry-contract";
 import {
+  cachedUserFunction,
   cachedUserRole,
   configureOrgDomainPersistence,
   recomputeOrgDomain,
@@ -169,6 +175,7 @@ export function startTelemetryTicker(deps: SnapshotDeps): void {
   if (!isTelemetryReady()) return;
   stopTelemetryTicker();
   setTelemetryRoleResolver(cachedUserRole);
+  setTelemetryFunctionResolver(cachedUserFunction);
 
   const tick = async () => {
     try {
@@ -207,5 +214,6 @@ export function stopTelemetryTicker(): void {
   tickTimer = null;
   firstTimer = null;
   setTelemetryRoleResolver(null);
+  setTelemetryFunctionResolver(null);
   configureOrgDomainPersistence(null);
 }

package/src/telemetry-ui-events.ts

@@ -15,6 +15,7 @@ interface PropertySpec {
   minimum?: number;
   required?: boolean;
   nullable?: boolean;
+  items?: PropertySpec;
 }
 
 interface CatalogEntry {
@@ -62,8 +63,8 @@ export function uiEventEmitter(event: string): string | undefined {
 }
 
 function resolveSpec(spec: PropertySpec): PropertySpec {
-  if (!spec.ref) return spec;
-  return { ...file.definitions[spec.ref], ...spec };
+  const resolved = spec.ref ? { ...file.definitions[spec.ref], ...spec } : spec;
+  return resolved.items ? { ...resolved, items: resolveSpec(resolved.items) } : resolved;
 }
 
 function typeMatches(type: string | undefined, value: unknown): boolean {
@@ -117,6 +118,12 @@ export function validateUiEvent(event: string, properties: Record<string, unknow
     if (spec.enum && !spec.enum.includes(value as string)) {
       problems.push(`"${key}" must be one of ${spec.enum.join(", ")}`);
     }
+    if (Array.isArray(value) && spec.items?.enum) {
+      const allowed = spec.items.enum;
+      if (value.some((item) => !allowed.includes(item))) {
+        problems.push(`"${key}" items must be one of ${allowed.join(", ")}`);
+      }
+    }
     if (typeof spec.minimum === "number" && typeof value === "number" && value < spec.minimum) {
       problems.push(`"${key}" must be at least ${spec.minimum}`);
     }

package/src/telemetry.ts

@@ -22,7 +22,7 @@ import {
   validOrgDomain,
   validOrgId,
 } from "./telemetry-context";
-import type { PropsFor, TelemetryEventName } from "./telemetry-contract";
+import type { EventContext, PropsFor, TelemetryEventName } from "./telemetry-contract";
 import { isEnvFlagEnabled } from "./utils/env-flag";
 import { getNodeEnv } from "./utils/node-env";
 import { normalizeOrgWebsite } from "./utils/org-website";
@@ -68,6 +68,7 @@ let cachedOrgId: string | undefined;
 /** Email domain of the org's admin, set by the API server (`setTelemetryOrgDomain`). */
 let cachedOrgDomain: string | undefined;
 let roleResolver: ((userId: string) => TelemetryUserRole | undefined) | null = null;
+let functionResolver: ((userId: string) => EventContext["user_function"]) | null = null;
 let identityReloader: (() => Promise<void>) | null = null;
 let lastIdentityLoadAt = 0;
 let source = "unknown";
@@ -510,6 +511,13 @@ export function setTelemetryRoleResolver(
   roleResolver = resolver;
 }
 
+/** API server only: cache-backed lookup of the actor's job function. */
+export function setTelemetryFunctionResolver(
+  resolver: ((userId: string) => EventContext["user_function"]) | null,
+): void {
+  functionResolver = resolver;
+}
+
 /**
  * True when `track()` would send: telemetry is on, an install ID exists and an
  * org ID resolved. Emitters that record "already sent" state check this first.
@@ -630,6 +638,7 @@ function emit(
   metadata?: Record<string, unknown>,
   actor?: TelemetryActor,
   emitter: string = source,
+  identity?: { orgName: string; orgWebsite: string },
 ): void {
   if (!isTelemetryEnabled() || !installationId) return;
   maybeRefreshOrgIdentity();
@@ -639,7 +648,9 @@ function emit(
     const occurredAt = new Date().toISOString();
     const sentFor = installationId;
     const isCloud = cachedIsCloud || isCloudDeployment();
-    const orgIdentity = getOrgIdentity();
+    const orgIdentity = identity
+      ? { ...getOrgIdentity(), organization_name: identity.orgName }
+      : getOrgIdentity();
     const userId = actor?.userId?.trim() || undefined;
     const payload = {
       schema_version: 2 as const,
@@ -653,7 +664,7 @@ function emit(
         orgId,
         orgName: orgIdentity.organization_name,
         orgDomain: cachedOrgDomain,
-        orgWebsite: normalizeOrgWebsite(process.env.SWARM_ORG_WEBSITE),
+        orgWebsite: identity?.orgWebsite ?? normalizeOrgWebsite(process.env.SWARM_ORG_WEBSITE),
         installationId,
         actor: userId ? { userId, role: actor?.role ?? roleResolver?.(userId) ?? null } : undefined,
         isCloud,
@@ -661,8 +672,10 @@ function emit(
         swarmVersion: pkg.version,
         installMethod: cachedInstallMethod,
         installPreset: cachedInstallPreset,
-        // Stays null until the dashboard reports where the visitor came from.
-        acquisitionSource: null,
+        acquisitionSource: process.env.SWARM_ORG_ACQUISITION_SOURCE,
+        teamSize: process.env.SWARM_ORG_TEAM_SIZE,
+        useCase: process.env.SWARM_ORG_USE_CASE,
+        userFunction: userId ? functionResolver?.(userId) : undefined,
       }),
       properties: normalizeProperties(event, {
         ...properties,
@@ -742,6 +755,7 @@ export function _resetTelemetryStateForTests(): void {
   cachedOrgId = undefined;
   cachedOrgDomain = undefined;
   roleResolver = null;
+  functionResolver = null;
   identityReloader = null;
   lastIdentityLoadAt = 0;
 }
@@ -820,6 +834,27 @@ export const telemetry = {
     );
   },
 
+  /**
+   * Public-ranking events. The API passes the org identity it just read from
+   * config, so a listing built right after an identity edit still matches the
+   * envelope's `org_name` / `org_website` (the proxy rejects a mismatch) before
+   * the debounced config reload updates `process.env`.
+   */
+  ranking<S extends EventSuffix<"ranking">>(
+    event: S,
+    props: FamilyProps<"ranking", S>,
+    identity?: { orgName: string; orgWebsite: string },
+  ): void {
+    emit(
+      `ranking.${event}`,
+      props as Record<string, unknown>,
+      undefined,
+      undefined,
+      source,
+      identity,
+    );
+  },
+
   org<S extends EventSuffix<"org">>(event: S, props: FamilyProps<"org", S>): void {
     emit(`org.${event}`, props as Record<string, unknown>, undefined);
   },

package/src/tests/app-action-run-tool.test.ts

@@ -0,0 +1,178 @@
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { createServer as createHttpServer } from "node:http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AppRecord, createApp } from "../apps/store";
+import { closeDb, createAgent, getTaskById, initDb } from "../be/db";
+import { upsertScriptByName } from "../be/scripts/db";
+import { handleCore } from "../http/core";
+import { handleMcpBridge } from "../http/mcp-bridge";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import { LEGACY_POLICY, type LegacyRule } from "../rbac";
+import { isMcpToolAllowedForScripts } from "../scripts-runtime/sdk-allowlist";
+import { registerAppActionRunTool } from "../tools/app-action-run";
+import { markExtensionRequestOrigin, markScriptSdkRequestOrigin } from "../tools/utils";
+import { SKIP_SANDBOX_SPAWN_TESTS } from "./sandbox-spawn-test-helpers";
+import { listenOnFreePort } from "./test-net";
+import { CHILD_PROCESS_TEST_BUDGET_MS } from "./test-proc";
+
+const dbPath = `/private/tmp/test-app-action-run-tool-${process.pid}.sqlite`;
+const agentId = crypto.randomUUID();
+const ownerId = crypto.randomUUID();
+const apiKey = "example-app-action-run-key";
+const previousKey = process.env.AGENT_SWARM_API_KEY;
+const previousBase = process.env.MCP_BASE_URL;
+const definition: AppRecord["definition"] = {
+  schemaVersion: 1,
+  models: { note: { columns: { title: { kind: "string" } } } },
+  actions: { triage: { kind: "task", prompt: "Triage the notes." } },
+  pages: { main: { root: "root", elements: { root: { type: "Container", props: {} } } } },
+  defaultPage: "main",
+};
+type ToolResult = {
+  isError?: boolean;
+  structuredContent: {
+    message: string;
+    data: { ok: boolean; taskId: string; status: string; result?: unknown };
+  };
+};
+let handler: (args: unknown, extra: unknown) => Promise<ToolResult>;
+let appId: string;
+
+async function removeDb() {
+  for (const suffix of ["", "-wal", "-shm"]) await unlink(dbPath + suffix).catch(() => undefined);
+}
+beforeAll(async () => {
+  process.env.AGENT_SWARM_API_KEY = apiKey;
+  await removeDb();
+  initDb(dbPath);
+  await createAgent({ id: agentId, name: "Action invoker", isLead: false, status: "idle" });
+  await createAgent({ id: ownerId, name: "Script owner", isLead: true, status: "idle" });
+  appId = (await createApp({ name: "Action tool", definition })).id;
+  const server = new McpServer({ name: "app-action-run-tool", version: "1.0.0" });
+  registerAppActionRunTool(server);
+  handler = (server as unknown as { _registeredTools: Record<string, { handler: typeof handler }> })
+    ._registeredTools["app-action-run"]!.handler;
+});
+afterAll(async () => {
+  closeDb();
+  await removeDb();
+  if (previousKey === undefined) delete process.env.AGENT_SWARM_API_KEY;
+  else process.env.AGENT_SWARM_API_KEY = previousKey;
+  if (previousBase === undefined) delete process.env.MCP_BASE_URL;
+  else process.env.MCP_BASE_URL = previousBase;
+});
+function call(
+  action: string,
+  input: Record<string, unknown> = {},
+  origin?: "script-sdk" | "extension",
+  id = agentId,
+  target = appId,
+) {
+  const extra = { sessionId: "action-tool", requestInfo: { headers: { "x-agent-id": id } } };
+  if (origin === "script-sdk") markScriptSdkRequestOrigin(extra);
+  if (origin === "extension") markExtensionRequestOrigin(extra);
+  return handler({ appId: target, action, input }, extra);
+}
+
+test("runs task actions with the verified caller and the REST response shape", async () => {
+  const output = await call("triage", { caller: { kind: "guest", id: "forged" } });
+  expect(output.isError).not.toBe(true);
+  expect(output.structuredContent).toMatchObject({ ok: true, status: "pending" });
+  const task = await getTaskById(output.structuredContent.taskId);
+  expect(task?.task).toContain(`"kind":"agent","id":"${agentId}","name":"Action invoker"`);
+});
+
+test("refuses script and extension origins and stays outside the SDK allowlist", async () => {
+  for (const origin of ["script-sdk", "extension"] as const) {
+    const output = await call("triage", {}, origin);
+    expect(output.isError).toBe(true);
+    expect(output.structuredContent.message).toContain("cannot run app actions");
+  }
+  expect(isMcpToolAllowedForScripts("app-action-run")).toBe(false);
+});
+
+test("rejects missing agents, apps, actions, and denied principals", async () => {
+  expect((await call("triage", {}, undefined, "")).isError).toBe(true);
+  expect((await call("triage", {}, undefined, agentId, "missing")).isError).toBe(true);
+  expect((await call("missing")).isError).toBe(true);
+  const policy = LEGACY_POLICY as unknown as Record<"app.use", LegacyRule>;
+  const original = policy["app.use"];
+  policy["app.use"] = { name: "deny-actions", denyReason: "denied actions", evaluate: () => false };
+  try {
+    expect((await call("triage")).isError).toBe(true);
+  } finally {
+    policy["app.use"] = original;
+  }
+});
+
+test.skipIf(SKIP_SANDBOX_SPAWN_TESTS)(
+  "runs script actions as the owner while preserving the invoking agent caller",
+  async () => {
+    const server = createHttpServer(async (req, res) => {
+      const id = req.headers["x-agent-id"] as string | undefined;
+      if (await handleCore(req, res, id, apiKey)) return;
+      if (
+        await handleMcpBridge(
+          req,
+          res,
+          getPathSegments(req.url ?? ""),
+          parseQueryParams(req.url ?? ""),
+          id,
+        )
+      )
+        return;
+      res.writeHead(404).end();
+    });
+    try {
+      const port = await listenOnFreePort(server);
+      process.env.MCP_BASE_URL = `http://localhost:${port}`;
+      const saved = await upsertScriptByName({
+        name: "action_tool_owner",
+        scope: "agent",
+        scopeId: ownerId,
+        agentId: ownerId,
+        source: `export default async function(args, ctx) {
+        const response = await ctx.swarm.app_row_create({ appId: args.app.id, model: "note", values: { title: "owner-write" } });
+        return { caller: args.caller, row: (response?.data ?? response).row };
+      }`,
+        description: "Owner action fixture",
+        intent: "Verify script owner and caller",
+        signatureJson: "{}",
+        typeChecked: true,
+        embeddingMode: "skip",
+      });
+      const app = await createApp({
+        name: "Script action",
+        definition: {
+          ...definition,
+          actions: {
+            write: {
+              kind: "script",
+              scriptId: saved.script.id,
+              args: { caller: { kind: "guest", id: "default-forgery" } },
+            },
+          },
+        },
+      });
+      const output = await call(
+        "write",
+        { caller: { kind: "operator", id: "forged" } },
+        undefined,
+        agentId,
+        app.id,
+      );
+      expect(output.isError).not.toBe(true);
+      expect(output.structuredContent).toMatchObject({
+        ok: true,
+        result: {
+          caller: { kind: "agent", id: agentId, name: "Action invoker" },
+          row: { title: "owner-write", createdBy: `agent:${ownerId}` },
+        },
+      });
+    } finally {
+      if (server.listening) await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  },
+  CHILD_PROCESS_TEST_BUDGET_MS,
+);