@desplega.ai/agent-swarm 2.5.0 → 2.5.2

package/src/http/user-roles.ts

@@ -0,0 +1,173 @@
+/**
+ * RBAC role assignment for people.
+ *
+ *   GET /api/rbac/roles
+ *   GET /api/users/:id/roles
+ *   PUT /api/users/:id/roles
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { getUserById } from "../be/db";
+import {
+  getUserGrant,
+  InvalidRoleSetError,
+  LastAdminError,
+  listRbacRoles,
+  listUserRoles,
+  PRIMARY_ROLE_NAMES,
+  setUserRoles,
+} from "../be/rbac-roles";
+import { recordIdentityEvent } from "../be/users";
+import { can, isRbacEnabled } from "../rbac";
+import { RbacRoleSchema, UserRbacRolesSchema } from "../types";
+import { getRequestAuth } from "../utils/request-auth-context";
+import { getOperatorActor } from "./operator-actor";
+import { agentFirstPrincipal, rejectGuest } from "./request-principal";
+import { route } from "./route-def";
+import { jsonError } from "./utils";
+
+const listRolesRoute = route({
+  method: "get",
+  path: "/api/rbac/roles",
+  pattern: ["api", "rbac", "roles"],
+  operationId: "rbac_listRoles",
+  summary: "List RBAC roles with their verbs",
+  tags: ["Users"],
+  responses: {
+    200: { description: "Role catalog", schema: z.object({ roles: z.array(RbacRoleSchema) }) },
+  },
+});
+
+const getUserRolesRoute = route({
+  method: "get",
+  path: "/api/users/{id}/roles",
+  pattern: ["api", "users", null, "roles"],
+  operationId: "users_getRbacRoles",
+  summary: "Get a user's RBAC roles",
+  tags: ["Users"],
+  params: z.object({ id: z.string().min(1) }),
+  responses: {
+    200: { description: "The user's roles", schema: UserRbacRolesSchema },
+    404: { description: "User not found" },
+  },
+});
+
+const setUserRolesRoute = route({
+  method: "put",
+  path: "/api/users/{id}/roles",
+  pattern: ["api", "users", null, "roles"],
+  operationId: "users_setRbacRoles",
+  summary: "Set a user's RBAC roles",
+  description: `Replaces the user's roles. The set holds exactly one of ${PRIMARY_ROLE_NAMES.join(", ")} plus any extra roles. Demoting a user below admin removes the ability to answer approval requests, even when the user is listed as an approver. Fails with 409 when it would leave no active admin.`,
+  tags: ["Users"],
+  params: z.object({ id: z.string().min(1) }),
+  body: z.object({ roles: z.array(z.string().min(1)).min(1) }).strict(),
+  responses: {
+    200: { description: "The user's roles after the change", schema: UserRbacRolesSchema },
+    400: { description: "Invalid role set" },
+    403: { description: "Not allowed to change roles" },
+    404: { description: "User not found" },
+    409: { description: "Would leave no active admin" },
+  },
+  rbac: { permission: "user.role.manage" },
+});
+
+async function composeRoles(userId: string) {
+  const [catalog, held] = await Promise.all([listRbacRoles(), listUserRoles(userId)]);
+  const names = new Set(held.map((role) => role.name));
+  return { userId, roles: catalog.filter((role) => names.has(role.name)) };
+}
+
+/** Operator or user only; agents never change human roles, even with the shared key. */
+async function ensureRoleManager(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (rejectGuest(req, res)) return false;
+  const auth = getRequestAuth(req);
+  if (auth?.kind !== "operator" && auth?.kind !== "user") {
+    jsonError(res, "Role changes require operator or user credentials", 403);
+    return false;
+  }
+  const header = req.headers["x-agent-id"];
+  const decision = can({
+    principal: await agentFirstPrincipal(req, Array.isArray(header) ? header[0] : header),
+    verb: "user.role.manage",
+    resource: { kind: "none" },
+    source: "http",
+  });
+  if (!decision.allow) {
+    jsonError(res, decision.reason, 403);
+    return false;
+  }
+  // A custom role holding user.role.manage must not be able to grant admin.
+  if (auth.kind === "user" && isRbacEnabled() && !(await getUserGrant(auth.userId)).grantsAll) {
+    jsonError(res, "Role changes require a grant-all role", 403);
+    return false;
+  }
+  return true;
+}
+
+export async function handleUserRoles(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (listRolesRoute.match(req.method, pathSegments)) {
+    if (rejectGuest(req, res)) return true;
+    listRolesRoute.respond(res, 200, { roles: await listRbacRoles() });
+    return true;
+  }
+
+  if (getUserRolesRoute.match(req.method, pathSegments)) {
+    if (rejectGuest(req, res)) return true;
+    const parsed = await getUserRolesRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await getUserById(parsed.params.id))) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+    getUserRolesRoute.respond(res, 200, await composeRoles(parsed.params.id));
+    return true;
+  }
+
+  if (setUserRolesRoute.match(req.method, pathSegments)) {
+    const parsed = await setUserRolesRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureRoleManager(req, res))) return true;
+    const actor = getOperatorActor(req, res);
+    if (!actor) return true;
+    const userId = parsed.params.id;
+    if (!(await getUserById(userId))) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+    try {
+      const { before, after } = await setUserRoles(
+        userId,
+        parsed.body.roles,
+        actor.kind === "user" ? actor.id : null,
+      );
+      await recordIdentityEvent(
+        userId,
+        "profile_changed",
+        actor,
+        { rbacRoles: before },
+        { rbacRoles: after },
+      );
+    } catch (err) {
+      if (err instanceof LastAdminError) {
+        jsonError(res, "last_admin", 409);
+        return true;
+      }
+      if (err instanceof InvalidRoleSetError) {
+        jsonError(res, err.message, 400);
+        return true;
+      }
+      throw err;
+    }
+    setUserRolesRoute.respond(res, 200, await composeRoles(userId));
+    return true;
+  }
+
+  return false;
+}

package/src/http/users.ts

@@ -45,6 +45,7 @@ import {
   updateUser,
   upsertBudget,
 } from "../be/db";
+import { assertNotLastAdmin, LastAdminError } from "../be/rbac-roles";
 import {
   getUserIdentities,
   type IdentityEvent,
@@ -484,6 +485,7 @@ const mergeUsersRoute = route({
     400: { description: "Validation error (e.g. target == source)" },
     401: { description: "Unauthorized" },
     404: { description: "Target or source user not found" },
+    409: { description: "Source is the last active admin (last_admin)" },
   },
   auth: { apiKey: true },
 });
@@ -1071,6 +1073,9 @@ export async function handleUsers(
           }
         }
 
+        // The source's roles go with it; never leave the swarm without an admin.
+        await assertNotLastAdmin(sourceId);
+
         // Delete source — CASCADE cleans up any leftover external_ids row that
         // we may have missed. Retained user references move to the target.
         await deleteUser(sourceId, targetId);
@@ -1095,6 +1100,10 @@ export async function handleUsers(
       });
       mergeUsersRoute.respond(res, 200, { user: mergedUser });
     } catch (err) {
+      if (err instanceof LastAdminError) {
+        jsonError(res, "last_admin", 409);
+        return true;
+      }
       jsonError(res, err instanceof Error ? err.message : "Failed to merge users", 500);
     }
     return true;

package/src/http/x.ts

@@ -15,12 +15,12 @@ import {
   restoreScratchScriptLastUsedIfUnchanged,
   touchScratchScriptLastUsed,
 } from "../be/scripts/db";
+import { runScriptWithRunCredential } from "../be/scripts/run-credential";
 import {
   MAX_SCRIPT_WALL_CLOCK_MS,
   MIN_SCRIPT_WALL_CLOCK_MS,
 } from "../scripts-runtime/executors/types";
 import type { RunScriptOutput } from "../scripts-runtime/loader";
-import { runScript } from "../scripts-runtime/loader";
 import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
 import { validateJsonSchema } from "../workflows/json-schema-validator";
 import { route } from "./route-def";
@@ -242,7 +242,7 @@ export async function handleX(
   const credentials = await buildScriptCredentialBindingsWithFailures({
     agentId: endpoint.agentId,
   });
-  const output = await runScript({
+  const output = await runScriptWithRunCredential({
     source: script.source,
     args: args ?? null,
     fsMode: "none",

package/src/integrations/chat-sdk/commands.ts

@@ -63,7 +63,19 @@ function helpText(): string {
   return ["Commands:", ...CHAT_COMMANDS.map((c) => `/${c.command}: ${c.description}`)].join("\n");
 }
 
-function shortId(task: AgentTask): string {
+/**
+ * Telegram sends `/start` when a user opens a bot DM. It stays out of
+ * `CHAT_COMMANDS`, so the `/` menu does not list it.
+ */
+function welcomeText(): string {
+  return [
+    "Hi! Send a message here (in a group, mention me) and the swarm picks it up. Each answer arrives as a reply to your message.",
+    "",
+    helpText(),
+  ].join("\n");
+}
+
+export function shortId(task: Pick<AgentTask, "id">): string {
   return task.id.slice(0, 8);
 }
 
@@ -115,6 +127,7 @@ export async function runChatCommand(
 ): Promise<string> {
   const name = command.replace(/^\//, "").toLowerCase();
   if (name === "help") return helpText();
+  if (name === "start") return welcomeText();
   if (!CHAT_COMMANDS.some((c) => c.command === name)) {
     return `Unknown command /${name}.\n${helpText()}`;
   }

package/src/integrations/chat-sdk/inbound.ts

@@ -32,6 +32,12 @@ import { getChatThreadResetAt } from "./commands";
 import { type ChatAddressedReason, formatChatHeaderFacts, readChatMessageFacts } from "./facts";
 import { errorMessage } from "./logger";
 import { emitChatMessageSent, postChatMessage } from "./outbound";
+import {
+  chatAdapterReacts,
+  clearChatMessageReactions,
+  setChatMessageReaction,
+  wantsChatTextAck,
+} from "./reactions";
 import {
   type ChatAgentMatch,
   type ChatRouteTarget,
@@ -154,9 +160,14 @@ export async function handleChatInbound(
       console.log(
         `[chat-sdk] ${adapter} message steered task ${steering.task.id} (${steering.result.outcome})`,
       );
+      await setChatMessageReaction(adapter, thread.id, message.id, "steered");
+      if (!(await wantsChatTextAck(adapter, thread.channelId))) return;
       try {
         const ack = formatChatSteeringAck(steering.result);
-        const sent = await thread.post({ markdown: ack });
+        // Telegram threads the ack under the steering message; other adapters post it.
+        const sent = thread.adapter.reply
+          ? await thread.reply(message, { markdown: ack })
+          : await thread.post({ markdown: ack });
         emitChatMessageSent({
           adapter,
           channelId: thread.channelId,
@@ -177,6 +188,9 @@ export async function handleChatInbound(
   }
 
   if (text || attachments.length > 0) {
+    // Subscribed-thread messages may be dropped by the router at flush time;
+    // they get typing and a reaction once a task exists (see flushChatThread).
+    const acknowledge = kind !== "subscribed";
     bufferChatMessage(thread.id, {
       messageId: message.id,
       channelId: thread.channelId,
@@ -186,12 +200,14 @@ export async function handleChatInbound(
       botMentioned: mentioned || facts.replyToBot,
       isDirectMessage,
       addressed,
+      reacted: acknowledge && chatAdapterReacts(adapter),
       facts,
       attachments,
     });
-    // Subscribed-thread messages may be dropped by the router at flush time;
-    // they get typing once a task exists (see flushChatThread).
-    if (kind !== "subscribed") startTypingKeepalive(adapter, thread.id);
+    if (acknowledge) {
+      startTypingKeepalive(adapter, thread.id);
+      await setChatMessageReaction(adapter, thread.id, message.id, immediate ? "now" : "accepted");
+    }
   }
   if (immediate) await instantFlushChat(thread.id);
 }
@@ -377,6 +393,9 @@ export async function flushChatThread(
   // One task carries every sender's text, so a batch from several people
   // gets no requester: one sender's identity must not vouch for another's words.
   const otherSenders = new Set(items.map((item) => item.userId)).size - 1;
+  // The task answers the newest message; it alone carries the reaction lifecycle.
+  const answered = items.at(-1) ?? first;
+  const reacted = items.filter((item) => item.reacted).map((item) => item.messageId);
 
   // After `/reset` the thread's earlier tasks are not context: the new task gets
   // no parent and no thread history older than the reset.
@@ -418,6 +437,7 @@ export async function flushChatThread(
       scrubSecrets(routeResult.reason),
     );
     stopTypingKeepalive(threadId);
+    await clearChatMessageReactions(adapter, threadId, reacted);
     return;
   }
 
@@ -433,12 +453,14 @@ export async function flushChatThread(
   if (!target) {
     console.log(`[chat-sdk] ${threadId}: message not addressed to the swarm, ignored`);
     stopTypingKeepalive(threadId);
+    await clearChatMessageReactions(adapter, threadId, reacted);
     return;
   }
 
   if (target.kind === "workflow") {
-    // A workflow run has no relay that would stop the indicator.
+    // A workflow run has no relay that would stop the indicator or end the reaction.
     stopTypingKeepalive(threadId);
+    await clearChatMessageReactions(adapter, threadId, reacted);
     try {
       // The adapter verified the platform signature, and the workflow id comes
       // from an operator mapping or an extension, never from the message.
@@ -533,6 +555,11 @@ export async function flushChatThread(
       // A human message in the thread: never answer it in the previous task's
       // structured-output contract.
       inheritParentOutputSchema: false,
+      // The relay answers as a reply to the newest buffered message. Always set
+      // explicitly: `createTask` copies the parent's anchor into a child that
+      // has none, and that would point at an older ask.
+      mentionMessageId: answered.messageId,
+      mentionChannelId: first.channelId,
     };
     try {
       const { task, unattached } = await createChatTaskWithFiles(description, options, inbound);
@@ -555,8 +582,16 @@ export async function flushChatThread(
     await subscribe(thread);
     // Subscribed-thread messages start typing only here, once a task exists.
     startTypingKeepalive(adapter, threadId);
+    await clearChatMessageReactions(
+      adapter,
+      threadId,
+      reacted.filter((id) => id !== answered.messageId),
+    );
+    if (!answered.reacted)
+      await setChatMessageReaction(adapter, threadId, answered.messageId, "accepted");
   } else {
     stopTypingKeepalive(threadId);
+    await clearChatMessageReactions(adapter, threadId, reacted);
   }
 }
 

package/src/integrations/chat-sdk/outbound.ts

@@ -76,12 +76,14 @@ export class ChatFileTooLargeError extends Error {
   }
 }
 
+type SentChunk = { id: string; threadId?: string };
+
 interface PostTarget {
   post(message: {
     markdown: string;
     files?: FileUpload[];
     attachments?: Attachment[];
-  }): Promise<{ id: string; threadId?: string }>;
+  }): Promise<SentChunk>;
 }
 
 /** A fence opener or closer: up to 3 spaces, then 3+ backticks or tildes. */
@@ -120,16 +122,22 @@ export function escapeTelegramHashLines(markdown: string): string {
     .join("\n");
 }
 
+/** `replyFirst` sends the first chunk as a native reply; later chunks are plain posts. */
 async function postChunks(
   adapter: string,
   target: PostTarget,
-  text: string,
+  parts: readonly string[],
+  replyFirst?: (message: { markdown: string }) => Promise<SentChunk>,
 ): Promise<{ messageIds: string[]; threadId?: string }> {
   const messageIds: string[] = [];
   let threadId: string | undefined;
-  for (const chunk of splitChatMessage(text, chatMessageLimit(adapter))) {
-    const markdown = adapter === "telegram" ? escapeTelegramHashLines(chunk) : chunk;
-    const sent = await target.post({ markdown });
+  const limit = chatMessageLimit(adapter);
+  for (const chunk of parts.flatMap((part) => splitChatMessage(part, limit))) {
+    const message = { markdown: adapter === "telegram" ? escapeTelegramHashLines(chunk) : chunk };
+    const sent =
+      replyFirst && messageIds.length === 0
+        ? await replyFirst(message)
+        : await target.post(message);
     messageIds.push(sent.id);
     threadId ??= sent.threadId;
   }
@@ -323,28 +331,45 @@ export function formatUnsentFilesNote(unsent: UnsentChatFile[]): string {
  * Delivery is at-least-once: a chunk failure re-posts earlier chunks on retry,
  * and a crash between the send and `markChatRelayDelivered` re-sends the
  * message.
+ *
+ * An array `text` is posted as one message per element, each still split at
+ * the limit; the caller uses it when its own markup must not be cut in two.
+ *
+ * `replyToMessageId` anchors the first chunk to that message on a thread
+ * target. Telegram sends it with `allow_sending_without_reply`, so a deleted
+ * target still gets the message, unthreaded.
  */
 export async function postChatMessage(args: {
   adapter: string;
   threadId?: string;
   channelId?: string;
-  text: string;
+  text: string | readonly string[];
   taskId?: string;
   files?: OutboundChatFile[];
+  replyToMessageId?: string;
 }): Promise<ChatPostResult> {
   // Ids come from tools and stored context keys. Check the Teams origin
   // before the adapter sends its token.
   assertTrustedChatTarget(args.threadId ?? args.channelId ?? "");
   const chat = getChatInstance(args.adapter);
   if (!chat) throw new ChatAdapterUnavailableError(args.adapter);
-  const text = scrubSecrets(args.text);
+  const parts = (typeof args.text === "string" ? [args.text] : args.text).map(scrubSecrets);
+  const text = parts.join("\n\n");
 
   let result: ChatPostResult;
   let target: PostTarget;
   if (args.threadId) {
     const thread = chat.thread(args.threadId);
     target = thread;
-    const sent = await postChunks(args.adapter, thread, text);
+    // Only adapters with a native reply (Telegram in this SDK version) anchor;
+    // the others post unanchored, as before.
+    const replyTo = args.replyToMessageId;
+    const sent = await postChunks(
+      args.adapter,
+      thread,
+      parts,
+      replyTo && thread.adapter.reply ? (message) => thread.reply(replyTo, message) : undefined,
+    );
     result = {
       adapter: args.adapter,
       threadId: thread.id,
@@ -355,7 +380,7 @@ export async function postChatMessage(args: {
   } else if (args.channelId) {
     const channel = chat.channel(args.channelId);
     target = channel;
-    const sent = await postChunks(args.adapter, channel, text);
+    const sent = await postChunks(args.adapter, channel, parts);
     result = {
       adapter: args.adapter,
       threadId: sent.threadId ?? channel.id,
@@ -373,7 +398,7 @@ export async function postChatMessage(args: {
     result.unsentFiles = sent.unsent;
     if (sent.unsent.length > 0) {
       const note = formatUnsentFilesNote(sent.unsent);
-      const noted = await postChunks(args.adapter, target, scrubSecrets(note));
+      const noted = await postChunks(args.adapter, target, [scrubSecrets(note)]);
       result.messageIds.push(...noted.messageIds);
     }
   }

package/src/integrations/chat-sdk/reactions.ts

@@ -0,0 +1,107 @@
+import { getKv } from "@/be/db";
+import type { ReactionEvent } from "@/integrations/reaction-events";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { errorMessage } from "./logger";
+import { chatChannelKey } from "./router";
+import { getChatInstance } from "./runtime";
+import { assertTrustedChatTarget } from "./teams-origin";
+
+/**
+ * Telegram reactions per lifecycle event. A bot may set only the emoji in the
+ * Bot API `ReactionTypeEmoji` list (https://core.telegram.org/bots/api#reactiontypeemoji),
+ * which has no ✅ or ❌. `✍` is U+270D with no variation selector, as listed.
+ * A bot sets one reaction per message, so each call replaces the previous one.
+ */
+export const TELEGRAM_REACTIONS: Record<ReactionEvent, string> = {
+  accepted: "👀",
+  buffered: "👀",
+  now: "⚡",
+  steered: "✍",
+  completed: "👍",
+  failed: "👎",
+};
+
+/** Adapters that show the task lifecycle as a reaction on the user's message. */
+const CHAT_REACTIONS: Readonly<Record<string, Record<ReactionEvent, string>>> = {
+  telegram: TELEGRAM_REACTIONS,
+};
+
+/** True when `adapter` shows the lifecycle as reactions instead of text acknowledgements. */
+export function chatAdapterReacts(adapter: string): boolean {
+  return adapter in CHAT_REACTIONS;
+}
+
+/**
+ * Set the reaction for `event` on one message. Best effort: an adapter without
+ * a reaction map is a no-op, and a platform error (Telegram answers
+ * `400 REACTION_INVALID` for an emoji a group admin disallowed) is logged and
+ * never thrown, so it cannot block delivery or fail the task.
+ */
+export async function setChatMessageReaction(
+  adapter: string,
+  threadId: string,
+  messageId: string,
+  event: ReactionEvent,
+): Promise<void> {
+  const emoji = CHAT_REACTIONS[adapter]?.[event];
+  if (!emoji) return;
+  try {
+    const target = getChatInstance(adapter)?.getAdapter(adapter);
+    if (!target) return;
+    assertTrustedChatTarget(threadId);
+    await target.addReaction(threadId, messageId, emoji);
+  } catch (error) {
+    console.warn(
+      scrubSecrets(
+        `[chat-sdk] Could not set the ${event} reaction on ${messageId} in ${threadId}: ${errorMessage(error)}`,
+      ),
+    );
+  }
+}
+
+/** Remove the bot's reaction from each message. Best effort, like {@link setChatMessageReaction}. */
+export async function clearChatMessageReactions(
+  adapter: string,
+  threadId: string,
+  messageIds: readonly string[],
+): Promise<void> {
+  if (!chatAdapterReacts(adapter) || messageIds.length === 0) return;
+  const target = getChatInstance(adapter)?.getAdapter(adapter);
+  if (!target) return;
+  for (const messageId of messageIds) {
+    try {
+      // Telegram clears the bot's whole reaction whatever emoji is named.
+      await target.removeReaction(threadId, messageId, TELEGRAM_REACTIONS.accepted);
+    } catch (error) {
+      console.warn(
+        scrubSecrets(
+          `[chat-sdk] Could not clear the reaction on ${messageId} in ${threadId}: ${errorMessage(error)}`,
+        ),
+      );
+    }
+  }
+}
+
+/** KV namespace of per-channel Chat SDK settings, keyed like the channel mappings. */
+export const CHAT_CHANNEL_SETTINGS_NAMESPACE = "integrations:chat:channel-settings";
+
+export interface ChatChannelSettings {
+  /** Also post the text steering acknowledgement on an adapter that reacts. */
+  textAcks?: boolean;
+}
+
+/**
+ * Whether a steering message gets a text acknowledgement. Adapters without
+ * reactions always get one; a reacting adapter only when its channel opts in.
+ */
+export async function wantsChatTextAck(adapter: string, channelId: string): Promise<boolean> {
+  if (!chatAdapterReacts(adapter)) return true;
+  try {
+    const row = await getKv(CHAT_CHANNEL_SETTINGS_NAMESPACE, chatChannelKey(adapter, channelId));
+    const settings = row?.value as ChatChannelSettings | null | undefined;
+    return typeof settings === "object" && settings !== null && settings.textAcks === true;
+  } catch (error) {
+    console.warn(`[chat-sdk] Could not read the channel settings: ${errorMessage(error)}`);
+    return false;
+  }
+}